temp

# Owl v1.0.13

## Bug fixes

- fix: slots: prevent infinite loop in some cases

.github/workflows/deploy.yml

@@ -0,0 +1,27 @@
+# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Node.js CI
+
+on:
+  pull_request:
+    branches: [ master, owl-next ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [12.x, 14.x, 16.x]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: npm run test
+    - run: npm run prettier

.gitignore

@@ -1,5 +1,6 @@
 /node_modules
 /dist
+
 npm-debug.log
 
 # misc
@@ -14,8 +15,19 @@ yarn-debug.log*
 yarn-error.log*
 
 package-lock.json
+yarn.lock
+
+#ide's
 .vscode
+.idea
+
 node_modules
 
 # Extras temp file
-/extras/owl.js
+/tools/owl.js
+
+release-notes.md
+
+.rpt2_cache
+
+/temp

COPYRIGHT

@@ -0,0 +1,14 @@
+
+Most of the files are
+
+  Copyright (c) 2004-2015 Odoo S.A.
+
+Many files also contain contributions from third
+parties. In this case the original copyright of
+the contributions can be traced through the
+history of the source version control system.
+
+When that is not the case, the files contain a prominent
+notice stating the original copyright and applicable
+license, or come with their own dedicated COPYRIGHT
+and/or LICENSE file.

README.md

@@ -1,19 +1,87 @@
-<h1 align="center">🦉 <a href="https://odoo.github.io/owl/">Odoo Web Library</a> 🦉</h1>
+<h1 align="center">🦉 <a href="https://odoo.github.io/owl/">OWL Framework</a> 🦉</h1>
 
-_A web framework for structured, dynamic and maintainable applications_
+ [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
+[![npm version](https://badge.fury.io/js/@odoo%2Fowl.svg)](https://badge.fury.io/js/@odoo%2Fowl)
+[![Downloads](https://img.shields.io/npm/dm/@odoo%2Fowl.svg)](https://www.npmjs.com/package/@odoo/owl)
+
+_Class based components with hooks, reactive state and concurrent mode_
 
 ## Project Overview
 
-The Odoo Web Library (OWL) is a small
-UI framework intended to be the basis for the [Odoo](https://www.odoo.com/) Web Client, and hopefully many
-other Odoo related projects. OWL's main feature is a _declarative component system_, with QWeb as a template engine, asynchronous rendering, and an underlying virtual dom.
+The Odoo Web Library (OWL) is a smallish (~<20kb gzipped) UI framework intended to
+be the basis for the [Odoo](https://www.odoo.com/) Web Client. Owl is a modern
+framework, written in Typescript, taking the best ideas from React and Vue in a
+simple and consistent way. Owl's main features are:
 
-**Try it online!** An online playground is available at [https://odoo.github.io/owl/playground](https://odoo.github.io/owl/playground) to let you experiment with the OWL framework.
+- a declarative component system,
+- a reactivity system based on hooks,
+- concurrent mode by default,
+- a store and a frontend router
 
-## OWL's design principles
+Owl components are defined with ES6 classes, they use QWeb templates, an
+underlying virtual DOM, integrates beautifully with hooks, and the rendering is
+asynchronous.
+
+**Try it online!** An online playground is available at
+[https://odoo.github.io/owl/playground](https://odoo.github.io/owl/playground)
+to let you experiment with the Owl framework. There are some code examples to
+showcase some interesting features.
+
+Owl is currently stable.  Possible future changes are explained in the
+[roadmap](roadmap.md).
+
+## Why Owl?
+
+Why did Odoo decide to make Yet Another Framework?  This is really a question
+that deserves [a long answer](doc/miscellaneous/why_owl.md). But in short, we believe that
+while the current state of the art frameworks are excellent, they are not
+optimized for our use case, and there is still room for something else.
+
+If you are interested in a comparison with React or Vue, you will
+find some more additional information [here](doc/miscellaneous/comparison.md).
+
+## Example
+
+Here is a short example to illustrate interactive components:
+
+```javascript
+const { Component, useState } = owl;
+const { xml } = owl.tags;
+
+class Counter extends Component {
+  static template = xml`
+    <button t-on-click="state.value++">
+      Click Me! [<t t-esc="state.value"/>]
+    </button>`;
+
+  state = useState({ value: 0 });
+}
+
+class App extends Component {
+  static template = xml`
+    <div>
+      <span>Hello Owl</span>
+      <Counter />
+    </div>`;
+
+  static components = { Counter };
+}
+
+const app = new App();
+app.mount(document.body);
+```
+
+Note that the counter component is made reactive with the [`useState` hook](doc/reference/hooks.md#usestate).
+Also, all examples here uses the [`xml` helper](doc/reference/tags.md#xml-tag) to define inline templates.
+But this is not mandatory, many applications will load templates separately.
+
+More interesting examples can be found on the
+[playground](https://odoo.github.io/owl/playground) application.
+
+## Design Principles
 
 OWL is designed to be used in highly dynamic applications where changing
-requirements are common, code needs to be maintained by large teams.
+requirements are common and code needs to be maintained by large teams.
 
 - **XML based**: templates are based on the XML format, which allows interesting
   applications. For example, they could be stored in a database and modified
@@ -26,62 +94,39 @@ requirements are common, code needs to be maintained by large teams.
   for various reasons (security/deployment/dynamic modules/specific assets tools),
   it is not ok to use standard web tools based on `npm`.
 
-Owl is not designed to be fast or small (even though it is quite good on those
-two topics). If you are interested in a comparison with React or Vue, you will
-find some more information [here](doc/comparison.md).
+Owl is not designed to be fast nor small (even though it is quite good on those
+two topics). It is a no nonsense framework to build applications. There is only
+one way to define components (with classes). There is no black magic. It just
+works.
 
-# Example
-
-Here is a short example to illustrate interactive widgets:
-
-```javascript
-class ClickCounter extends owl.Component {
-  state = { value: 0 };
-
-  increment() {
-    this.state.value++;
-  }
-}
-
-const TEMPLATES = `
-    <button t-name="ClickCounter" t-on-click="increment">
-        Click Me! [<t t-esc="state.value"/>]
-    </button>`;
-
-const qweb = new owl.QWeb(TEMPLATES);
-const counter = new ClickCounter({ qweb });
-counter.mount(document.body);
-```
-
-More interesting examples can be found on the [playground](https://odoo.github.io/owl/playground) application.
-
-## Installing/Building
-
-If you want to use a simple `<script>` tag, the last release can be downloaded here:
-
-- [owl-0.11.0.js](https://github.com/odoo/owl/releases/download/v0.11.0/owl.js)
-- [owl-0.11.0.min.js](https://github.com/odoo/owl/releases/download/v0.11.0/owl.min.js)
-
-Some npm scripts are available:
-
-| Command                | Description                                                                     |
-| ---------------------- | ------------------------------------------------------------------------------- |
-| `npm install`          | install every dependency required for this project                              |
-| `npm run build`        | build a bundle of _owl_ in the _/dist/_ folder                                  |
-| `npm run minify`       | minify the prebuilt owl.js file                                                 |
-| `npm run test`         | run all tests                                                                   |
-| `npm run test:watch`   | run all tests, and keep a watcher                                               |
-| `npm run extras`       | build extras applications, start a static server (see [here](extras/readme.md)) |
-| `npm run extras:watch` | same as `extras`, but with a watcher to rebuild owl                             |
 
 ## Documentation
 
-The complete documentation can be found [here](doc/readme.md). The most important sections are:
+A complete documentation for Owl can be found here:
 
-- [Quick Start](doc/quick_start.md)
-- [Component](doc/component.md)
-- [QWeb](doc/qweb.md)
+- [Main documentation page](doc/readme.md).
+
+Some of the most important pages are:
+
+- [Tutorial: TodoList application](doc/learning/tutorial_todoapp.md)
+- [How to start an Owl project](doc/learning/quick_start.md)
+- [QWeb templating language](doc/reference/qweb_templating_language.md)
+- [Component](doc/reference/component.md)
+- [Hooks](doc/reference/hooks.md)
+
+
+## Installing Owl
+
+Owl is available on `npm` and can be installed with the following command:
+
+```
+npm install @odoo/owl
+```
+
+If you want to use a simple `<script>` tag, the last release can be downloaded here:
+
+- [owl-1.0.13](https://github.com/odoo/owl/releases/tag/v1.0.13)
 
 ## License
 
-OWL is [GPL licensed](./LICENSE).
+OWL is [LGPL licensed](./LICENSE).

doc/animations.md

@@ -1,39 +0,0 @@
-# 🦉 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/comparison.md

@@ -1,194 +0,0 @@
-# Comparison with Vue/React
-
-OWL, React and Vue have the same main feature: they allow developers to build
-declarative user interfaces. To do that, all these frameworks uses a virtual dom. However, there are still obviously many differences.
-
-In this page, we try to highlight some of these differences. Obviously, some
-effort was done to be fair. However, if you disagree with some of the points
-discussed, feel free to open an issue/submit a PR to correct this text.
-
-- [Size](#size)
-- [Tooling/Build Step](#toolingbuild-step)
-- [Templating](#templating)
-- [Asynchronous rendering](#asynchronous-rendering)
-- [Reactiveness](#reactiveness)
-- [State Management](#state-management)
-
-### Size
-
-OWL is intended to be small and to work at a slightly lower level of abstraction
-than React and Vue. Also, jQuery is not the same kind of framework, but it is interesting to compare.
-
-| Framework                | Size (minified) | Size (minified, gzipped) |
-| ------------------------ | --------------- | ------------------------ |
-| OWL                      | 32kb            | 11kb                     |
-| Vue + VueX               |                 | 30kb                     |
-| React + ReactDOM + Redux |                 | 40kb                     |
-| jQuery                   | 86kb            | 30kb                     |
-
-### Tooling/Build step
-
-OWL is designed to be easy to use in a standalone way. For various reasons,
-Odoo does not want to rely on standard web tools (such as webpack), and OWL can
-be used by simply adding a script tag to a page.
-
-```html
-<script src="owl.min.js" />
-```
-
-In comparison, React encourages using JSX,
-which necessitate a build step, and most Vue applications uses single file
-components, which also necessitate a build step.
-
-On the flipside, external tooling may make it harder to use in some case, but it
-also brings a lot of benefits. And React/Vue have both a large ecosystem.
-
-### Templating
-
-OWL uses its own QWeb engine, which compiles templates on the
-frontend, as they are needed. This is extremely convenient for our use case, in
-particular because templates are described in XML files, and can be modified by
-XPaths. Since Odoo is at its heart a modular application, this is an important
-feature for us.
-
-```xml
-<div>
-  <button t-on-click="increment">Click Me! [<t t-esc="state.value"/>]</button>
-</div>
-```
-
-Vue is actually kind of similar. Its template language is kind of close to QWeb,
-with the `v` replaced by the `t`. However, it is also more fully featured. For
-example, Vue templates have slots, or event modifiers. A large difference is that
-most Vue applications will need to be built ahead of time, to compile the templates
-into javascript functions. Note that Vue has a separate build which includes the
-template compiler.
-
-In contrast, most React applications do not use a templating language, but write
-some JSX code, which is precompiled into plain JavaScript by a build step.
-
-```jsx
-class Clock extends React.Component {
-  render() {
-    return (
-      <div>
-        <h1>Hello, world!</h1>
-        <h2>It is {this.props.date.toLocaleTimeString()}.</h2>
-      </div>
-    );
-  }
-}
-```
-
-This has the advantage of having the full power of Javascript, but is less
-structured than a template language. Note that the tooling is quite impressive:
-there is a syntax highlighter for jsx here on github!
-
-### Asynchronous rendering
-
-This is actually a big difference between OWL and React/Vue: components in OWL
-are totally asynchronous. They have two asynchronous hooks in their lifecycle:
-
-- `willStart` (before the widget starts rendering)
-- `willUpdateProps` (before new props are set)
-
-Both these methods can be implemented and return a promise. The rendering will
-then wait for these promises to be completed before patching the DOM. This is
-useful for some use cases: for example, a widget may want to fetch an external
-library (a calendar widget may need a specialized calendar rendering library),
-in its willStart hook.
-
-```javascript
-class MyCalendarWidget extends owl.Component {
-    ...
-
-    willStart() {
-        return utils.lazyLoad('static/libs/fullcalendar/fullcalendar.js');
-    }
-    ...
-}
-```
-
-This may be dangerous (to stop the rendering waiting for the network), but it is
-extremely powerful as well, as demonstrated by the Odoo Web Client.
-
-Lazy loading static libraries can obviously be done with React/Vue, but it is
-more convoluted.
-
-### Reactiveness
-
-React has a simple model: whenever the state changes, it is
-replaced with a new state (via the setState method). Then, the DOM is patched.
-This is simple, efficient, and a little bit awkward to write.
-
-Vue is a little bit different: it replace magically the properties in the state
-by getters/setters. With that, it can notify components whenever the state that
-they read was changed.
-
-Owl is closer to vue: it also tracks magically the state properties, but it does
-only increment a counter whenever it changes (and a _deep_ counter for each of
-its parents). This assumes that the state is actually a tree.
-
-### State Management
-
-Managing the state of an application is a tricky issue. Many solutions have
-been proposed these last few years. It also depends on the kind of application we
-are talking about. A small application may not need much more than a simple
-object to contain its state.
-
-However, there are some common solutions for React and Vue: redux and vuex.
-Both of them are a centralized store that own the state, and they dictate how
-the state can be mutated.
-
-**Redux**
-
-In Redux, the state is mutated by reducers. Reducers are functions
-that modify the state by returning a different object:
-
-```javascript
-  ...
-  switch (action.type) {
-    case ADD_TODO: {
-      const { id, content } = action.payload;
-      return {
-        ...state,
-        allIds: [...state.allIds, id],
-        byIds: {
-          ...state.byIds,
-          [id]: {
-            content,
-            completed: false
-          }
-        }
-      };
-    }
-```
-
-This is a little bit awkward to write, but this allows the component system to
-check if a part of the state was changed. This is exactly what is done by the
-`connect` function: it create a _connected_ component, which is subscribed to
-the state and triggers a rerender if some part of the state was modified.
-
-**VueX**
-
-VueX is based on a different principle: the state is mutated through
-some special functions (the mutations), which modify the state in place:
-
-```javascript
-    function ({state}, payload) {
-        const { id, content } = payload;
-        const message = {id, content, completed: false};
-        state.messages.push(message)
-    }
-```
-
-This is simpler, but there is a little bit more happening behind the scene:
-each key from the state is silently replaced by getters and setters, and VueX
-keeps track of who get data, and retrigger a render when it was changed.
-
-**Owl**
-
-Owl store is a little bit like a mix of redux and vuex: it has mutations and
-actions, like VueX, it keeps track of the state changes, but it does not notify
-a component when the state changes.  Instead, components need to connect to the
-store like in redux, with a function that will listen to the relevant state.

doc/component.md

@@ -1,458 +0,0 @@
-# 🦉 OWL Component 🦉
-
-## Content
-
-- [Overview](#overview)
-- [Example](#example)
-- [Composition](#composition)
-- [Reference](#reference)
-  - [Properties](#properties)
-  - [Methods](#methods)
-  - [Lifecycle](#lifecycle)
-  - [Semantics](#semantics)
-- [Asynchronous rendering](#asynchronous-rendering)
-
-## Overview
-
-OWL components are the building blocks for user interface. They are designed to be:
-
-1. **declarative:** the user interface should be described in term of the state
-   of the application, not as a sequence of imperative steps.
-
-2. **composable:** each widget can seamlessly be created in a parent widget by
-   a simple directive in its template.
-
-3. **asynchronous rendering:** the framework will transparently wait for each
-   subwidgets to be ready before applying the rendering. It uses native promises
-   under the hood.
-
-4. **uses QWeb as a template system:** the templates are described in XML
-   and follow the QWeb specification. This is a requirement for Odoo.
-
-OWL components are defined as a subclass of Component. The rendering is
-exclusively done by a [QWeb](qweb.md) template (which needs to be preloaded in QWeb).
-Rendering a component generates a virtual dom representation
-of the widget, which is then patched to the DOM, in order to apply the changes in an efficient way.
-
-OWL components observe their states, and rerender themselves whenever it is
-changed. This is done by an [observer](observer.md).
-
-## Example
-
-Let us have a look at a simple component:
-
-```javascript
-class ClickCounter extends owl.Component {
-  state = { value: 0 };
-
-  increment() {
-    this.state.value++;
-  }
-}
-```
-
-```xml
-<button t-name="ClickCounter" t-on-click="increment">
-  Click Me! [<t t-esc="state.value"/>]
-</button>
-```
-
-Note that this code is written in ESNext style, so it will only run on the
-latest browsers without a transpilation step.
-
-This example show how a component should be defined: it simply subclasses the
-Component class. If no `template` key is defined, then
-Owl will use the component's name as template name. Here,
-a state object is defined. It is not mandatory to use the state object, but it
-is certainly encouraged. The state object is [observed](observer.md), and any
-change to it will cause a rerendering.
-
-## Composition
-
-The example above shows a QWeb template with a `t-on-click` directive. Widget
-templates are standard [QWeb](qweb.md) templates, but with an extra directive:
-`t-widget`. With the `t-widget` directive, widget templates can declare sub
-widgets:
-
-```xml
-<div t-name="ParentWidget">
-  <span>some text</span>
-  <t t-widget="MyWidget" t-props="{info: 13}"/>
-</div>
-```
-
-```js
-class ParentWidget extends owl.Component {
-    widgets = { MyWidget: MyWidget};
-    ...
-}
-```
-
-In this example, the `ParentWidget`'s template creates a widget `MyWidget` just
-after the span. See the [QWeb](qweb.md) documentation for more information on the
-`t-widget` directive.
-
-Note that the rendering context for the template is the widget itself. This means
-that the template can access `state`, `props`, `env`, or any methods defined in the widget.
-
-**CSS and style:** there is some specific support to allow the parent to declare
-additional css classes or style for the sub widget: css declared in `class`, `style`, `t-att-class` or `t-att-style` will be added to the
-root widget element.
-
-```xml
-<div t-name="ParentWidget">
-  <t t-widget="MyWidget" class="someClass" style="font-weight:bold;" t-props="{info: 13}"/>
-</div>
-```
-
-Warning: there is a small caveat with dynamic class attributes: since Owl needs
-to be able to add/remove proper classes whenever necessary, it needs to be aware
-of the possible classes. Otherwise, it will not be able to make the difference
-between a valid css class added by the component, or some custom code, and a
-class that need to be removed. This is why we only support the explicit syntax
-with a class object:
-
-```xml
-<t t-widget="MyWidget" t-att-class="{a: state.flagA, b: state.flagB}" />
-```
-
-## Reference
-
-An Owl component is a small class which represent a widget or some UI element.
-It exists in the context of an environment (`env`), which is propagated from a
-parent to its children. The environment needs to have a QWeb instance, which
-will be used to render the component template.
-
-Be aware that the name of the component may be significant: if a component does
-not define a `template` key, then Owl will lookup in QWeb to
-find a template with the component name (or one of its ancestor).
-
-### Properties
-
-- **`el`** (HTMLElement | null): reference to the DOM root node of the element. It is `null` when the
-  component is not mounted.
-
-- **`env`** (Object): the component environment, which contains a QWeb instance.
-
-- **`template`** (string, optional): if given, this is the name of the QWeb template that will render
-  the component.
-
-- **`state`** (Object): this is the location of the component's state, if there is
-  any. After the willStart method, the `state` property is observed, and each
-  change will cause the widget to rerender itself.
-
-- **`props`** (Object): this is an object given (in the constructor) by the parent
-  to configure the component. It can be dynamically changed later by the parent,
-  in some case. Note that `props` are owned by the parent, not by the component.
-  As such, it should not ever be modified by the component.
-
-- **`refs`** (Object): the `refs` object contains all references to sub DOM nodes
-  or sub widgets defined by a `t-ref` directive in the component's template.
-
-### Methods
-
-- **`mount(target)`** (async): this is the main way a component's hierarchy is added to the
-  DOM: the root component is mounted to a target HTMLElement. Obviously, this
-  is asynchronous, since each children need to be created as well. Most applications
-  will need to call `mount` exactly once, on the root component.
-
-- **`unmount()`**: in case a component need to be detached/removed from the DOM, this
-  method can be used. Most applications should not call `unmount`, this is more
-  useful to the underlying component system.
-
-- **`render()`** (async): calling this method directly will cause a rerender. Note
-  that this should be very rare to have to do it manually, the Owl framework is
-  most of the time responsible for doing that at an appropriate moment.
-
-  Note that the render method is asynchronous, so one cannot observe the updated
-  DOM in the same stack frame.
-
-- **`shouldUpdate(nextProps)`**: this method is called each time a component's props
-  are updated. It returns a boolean, which indicates if the widget should
-  ignore a props update. If it returns false, then `willUpdateProps` will not
-  be called, and no rendering will occur. Its default implementation is to
-  always return true. This is an optimization, similar to React's `shouldComponentUpdate`. Most of the time, this should not be used, but it
-  can be useful if we are handling large number of components.
-
-- **`updateEnv(nextEnv)`**: update the environment of a component and all its
-  children. This forces a complete rerender. For example, this could be useful
-  if we have a `isMobile` key in the environment, to decide if we want a mobile
-  interface or a destkop one.
-
-- **`set(target, key, value)`**. This method is necessary in some cases when we
-  need to modify the state of the component in a way that is not visible to the
-  observer (see [observer's technical limitations](observer.md#technical-limitations)).
-  For example, if we need to add a key to the state.
-
-- **`destroy()`**. As its name suggests, this method will remove the component,
-  and perform all necessary cleanup, such as unmounting the component, its children,
-  removing the parent/children relationship. This method should almost never be
-  called directly (except maybe on the root component), but should be done by the
-  framework instead.
-
-### Lifecycle
-
-A solid and robust component system needs useful hooks/methods to help
-developers write components. Here is a complete description of the lifecycle of
-a owl component:
-
-| Method                                           | Description                                           |
-| ------------------------------------------------ | ----------------------------------------------------- |
-| **[constructor](#constructor)**                  | constructor                                           |
-| **[willStart](#willStart)**                      | async, before first rendering                         |
-| **[mounted](#mounted)**                          | just after component is rendered and added to the DOM |
-| **[willUpdateProps](#willupdatepropsnextprops)** | async, before props update                            |
-| **[willPatch](#willpatch)**                      | just before the DOM is patched                        |
-| **[patched](#patchedsnapshot)**                  | just after the DOM is patched                         |
-| **[willUnmount](#willUnmount)**                  | just before removing component from DOM               |
-
-Notes:
-
-- hooks call order is precisely defined: `[willX]` hooks are called first on parent,
-  then on children, and `[Xed]` are called in the reverse order: first children,
-  then parent.
-- no hook method should ever be called manually. They are supposed to be
-  called by the owl framework whenever it is required.
-
-#### `constructor(parent, props)`
-
-The constructor is not exactly a hook, it is the regular,
-normal, constructor of the component. Since it is not a hook, you need to make
-sure that `super` is called.
-
-This is usually where you would set the initial state and the template of the
-component.
-
-```javascript
-  constructor(parent, props) {
-    super(parent, props);
-    this.state = {someValue: true};
-    this.template = 'mytemplate';
-  }
-```
-
-Note that with ESNext class fields, the constructor method does not need to be
-implemented in most cases:
-
-```javascript
-class ClickCounter extends owl.Component {
-  state = { value: 0 };
-
-  ...
-}
-```
-
-#### `willStart()`
-
-willStart is an asynchronous hook that can be implemented to
-perform some action before the initial rendering of a component.
-
-It will be called exactly once before the initial rendering. It is useful
-in some cases, for example, to load external assets (such as a JS library)
-before the widget is rendered. Another use case is to load data from a server.
-
-```javascript
-  async willStart() {
-    await owl.utils.loadJS("my-awesome-lib.js");
-  }
-```
-
-At this point, the component is not yet rendered. Note that a slow `willStart` method will slow down the rendering of the user
-interface. Therefore, some care should be made to make this method as
-fast as possible.
-
-The widget rendering will take place after `willStart` is completed.
-
-#### `mounted()`
-
-`mounted` is called each time a component is attached to the
-DOM, after the initial rendering and possibly later if the component was unmounted
-and remounted. At this point, the component is considered _active_. This is a good place to add some listeners, or to interact with the
-DOM, if the component needs to perform some measure for example.
-
-It is the opposite of `willUnmount`. If a component has been mounted, it will
-always be unmounted at some point in the future.
-
-The mounted method will be called recursively on each of its children. First,
-the parent, then all its children.
-
-Note that the state is now observed. It is however allowed (but not encouraged)
-to modify the state in the `mounted` hook. Doing so will cause a rerender,
-which will not be perceptible by the user, but will slightly slow down the
-component.
-
-#### `willUpdateProps(nextProps)`
-
-The willUpdateProps is an asynchronous hook, called just before new props
-are set. This is useful if the component needs some asynchronous task
-performed, depending on the props (for example, assuming that the props are
-some record Id, fetching the record data).
-
-```javascript
-  willUpdateProps(nextProps) {
-    return this.loadData({id: nextProps.id});
-  }
-```
-
-This hook is not called during the first render (but willStart is called
-and performs a similar job).
-
-#### `willPatch()`
-
-The willPatch hook is called just before the DOM patching process starts.
-It is not called on the initial render. This is useful to read some
-information from the DOM. For example, the current position of the
-scrollbar.
-
-Note that modifying the state object is not allowed here. This method is called just
-before an actual DOM patch, and is only intended to be used to save some local
-DOM state. Also, it will not be called if the widget is not in the DOM (this can
-happen with widgets with `t-keepalive`).
-
-The return value of this method will be given as the first argument of the
-corresponding `patched` call.
-
-#### `patched(snapshot)`
-
-This hook is called whenever a component did actually update its DOM (most
-likely via a change in its state/props or environment).
-
-This method is not called on the initial render. It is useful to interact
-with the DOM (for example, through an external library) whenever the
-component was patched. Note that this hook will not be called if the widget is
-not in the DOM (this can happen with widgets with `t-keepalive`).
-
-The `snapshot` parameter is the result of the previous `willPatch` call.
-
-Updating the widget state in this hook is possible, but not encouraged.
-One need to be careful, because updates here will cause rerender, which in
-turn will cause other calls to patched. So, we need to be particularly
-careful at avoiding endless cycles.
-
-#### `willUnmount()`
-
-willUnmount is a hook that is called each time just before a component is unmounted from
-the DOM. This is a good place to remove some listeners, for example.
-
-```javascript
-  mounted() {
-    this.env.bus.on('someevent', this, this.doSomething);
-  }
-  willUnmount() {
-    this.env.bus.off('someevent', this, this.doSomething);
-  }
-```
-
-This is the opposite method of `mounted`.
-
-### Semantics
-
-We give here an informal description of the way components are created/updated
-in an application. Here, ordered lists describe actions that are executed
-sequentially, bullet lists describe actions that are executed in parallel.
-
-**Scenario 1: initial rendering** Imagine we want to render the following component tree:
-
-```
-        A
-       / \
-      B   C
-         / \
-        D   E
-```
-
-Here is what happen whenever we mount the root
-component (with some code like `app.mount(document.body)`).
-
-1. `willStart` is called on `A`
-
-2. when it is done, template `A` is rendered.
-
-   - widget `B` is created
-     1. `willStart` is called on `B`
-     2. template `B` is rendered
-   - widget `C` is created
-     1. `willStart` is called on `C`
-     2. template `C` is rendered
-        - widget `D` is created
-          1. `willStart` is called on `D`
-          2. template `D` is rendered
-        - widget `E` is created
-          1. `willStart` is called on `E`
-          2. template `E` is rendered
-
-3. widget `A` is patched into a detached DOM element. This will create the actual
-   widget `A` DOM structure. The patching process will cause recursively the
-   patching of the `B`, `C`, `D` and `E` DOM trees. (so the actual full DOM tree is created
-   in one pass)
-
-4. the widget `A` root element is actually appended to `document.body`
-
-5. The method `mounted` is called recursively on all widgets in the following
-   order: `B`, `D`, `E`, `C`, `A`.
-
-**Scenario 2: rerendering a component**. Now, let's assume that the user clicked on some
-button in `C`, and this results in a state update, which is supposed to:
-
-- update `D`,
-- remove `E`,
-- add new widget `F`.
-
-So, the component tree should look like this:
-
-```
-        A
-       / \
-      B   C
-         / \
-        D   F
-```
-
-Here is what Owl will do:
-
-1. because of a state change, the method `render` is called on `C`
-2. template `C` is rendered again
-
-   - widget `D` is updated:
-     1. hook `willUpdateProps` is called on `D` (async)
-     2. template `D` is rerendered
-   - widget `F` is created:
-     1. hook `willStart` is called on `E` (async)
-     2. template `F` is rendered
-
-3. `willPatch` hooks are called recursively on widgets `C`, `D` (not on `F`,
-   because it is not mounted yet)
-
-4. widget `C` is patched, which will cause recursively:
-
-   2. `willUnmount` hook on `E`, then destruction of `E`,
-   3. (initial) patching of `F`, then hook `mounted` is called on `F`
-
-5. patching of `D`
-
-6. `patched` hooks are called on `D`, `C`
-
-## Asynchronous rendering
-
-Working with asynchronous code always adds a lot of complexity to a system. Whenever
-different parts of a system are active at the same time, one needs to think
-carefully about all possible interactions. Clearly, this is also true for Owl
-components.
-
-There are two different common problems with Owl asynchronous rendering model:
-
-- any widget can delay the rendering (initial and subsequent) of the whole
-  application
-- for a given widget, there are two independant situations that will trigger an
-  asynchronous rerendering: a change in the state, or a change in the props.
-  These changes may be done at different times, and Owl has no way of knowing
-  how to reconcile the resulting renderings.
-
-Here are a few tips on how to work with asynchronous widgets:
-
-1. minimize the use of asynchronous widgets!
-2. Maybe move the asynchronous logic in a store, which then triggers (mostly)
-   synchronous renderings
-3. Lazy loading external libraries is a good use case for async rendering. This
-   is mostly fine, because we can assume that it will only takes a fraction of a
-   second, and only once (see `owl.utils.loadJS`)

doc/learning/how_to_debug.md

@@ -0,0 +1,43 @@
+# 🦉 How to debug Owl applications 🦉
+
+Non trivial applications become quickly more difficult to understand. It is then
+useful to have a solid understanding of what is going on. To help with that,
+logging useful information is extremely valuable. There is a [javascript file](../../tools/debug.js) which can be evaluated in an application.
+
+Once it is executed, it will log a lot of information on each component main hooks. The following code is a minified version to make it easier to copy/paste:
+
+```
+function debugOwl(t,e){let n,o="[OWL_DEBUG]";function r(t){let e;try{e=JSON.stringify(t||{})}catch(t){e="<JSON error>"}return e.length>200&&(e=e.slice(0,200)+"..."),e}if(Object.defineProperty(t.Component,"current",{get:()=>n,set(s){n=s;const i=s.constructor.name;if(e.componentBlackList&&e.componentBlackList.test(i))return;if(e.componentWhiteList&&!e.componentWhiteList.test(i))return;let l;Object.defineProperty(n,"__owl__",{get:()=>l,set(n){!function(n,s,i){let l=`${s}<id=${i}>`,c=t=>console.log(`${o} ${l} ${t}`),u=t=>(!e.methodBlackList||!e.methodBlackList.includes(t))&&!(e.methodWhiteList&&!e.methodWhiteList.includes(t));u("constructor")&&c(`constructor, props=${r(n.props)}`);u("willStart")&&t.hooks.onWillStart(()=>{c("willStart")});u("mounted")&&t.hooks.onMounted(()=>{c("mounted")});u("willUpdateProps")&&t.hooks.onWillUpdateProps(t=>{c(`willUpdateProps, nextprops=${r(t)}`)});u("willPatch")&&t.hooks.onWillPatch(()=>{c("willPatch")});u("patched")&&t.hooks.onPatched(()=>{c("patched")});u("willUnmount")&&t.hooks.onWillUnmount(()=>{c("willUnmount")});const d=n.__render.bind(n);n.__render=function(...t){c("rendering template"),d(...t)};const h=n.render.bind(n);n.render=function(...t){const e=n.__owl__;let o="render";return e.isMounted||e.currentFiber||(o+=" (warning: component is not mounted, this render has no effect)"),c(o),h(...t)};const p=n.mount.bind(n);n.mount=function(...t){return c("mount"),p(...t)}}(s,i,(l=n).id)}})}}),e.logScheduler){let e=t.Component.scheduler.start,n=t.Component.scheduler.stop;t.Component.scheduler.start=function(){this.isRunning||console.log(`${o} scheduler: start running tasks queue`),e.call(this)},t.Component.scheduler.stop=function(){this.isRunning&&console.log(`${o} scheduler: stop running tasks queue`),n.call(this)}}if(e.logStore){let e=t.Store.prototype.dispatch;t.Store.prototype.dispatch=function(t,...n){return console.log(`${o} store: action '${t}' dispatched. Payload: '${r(n)}'`),e.call(this,t,...n)}}}
+debugOwl(owl, {
+  // componentBlackList: /App/,  // regexp
+  // componentWhiteList: /SomeComponent/, // regexp
+  // methodBlackList: ["mounted"], // list of method names
+  // methodWhiteList: ["willStart"], // list of method names
+  logScheduler: false,  // display/mute scheduler logs
+  logStore: true,     // display/mute store logs
+});
+```
+
+The above code, once pasted somewhere in the main javascript file of an owl
+application, will log information looking like this:
+
+```
+[OWL_DEBUG] TodoApp<id=1> constructor, props={}
+[OWL_DEBUG] TodoApp<id=1> mount
+[OWL_DEBUG] TodoApp<id=1> willStart
+[OWL_DEBUG] TodoApp<id=1> rendering template
+[OWL_DEBUG] TodoItem<id=2> constructor, props={"id":2,"completed":false,"title":"hey"}
+[OWL_DEBUG] TodoItem<id=2> willStart
+[OWL_DEBUG] TodoItem<id=3> constructor, props={"id":4,"completed":false,"title":"aaa"}
+[OWL_DEBUG] TodoItem<id=3> willStart
+[OWL_DEBUG] TodoItem<id=2> rendering template
+[OWL_DEBUG] TodoItem<id=3> rendering template
+[OWL_DEBUG] TodoItem<id=3> mounted
+[OWL_DEBUG] TodoItem<id=2> mounted
+[OWL_DEBUG] TodoApp<id=1> mounted
+```
+
+Each component has an internal `id`, which is very useful when debugging.
+
+Note that it is certainly useful to run this code at some point in an application,
+just to get a feel of what each user action implies, for the framework.

doc/learning/how_to_test.md

@@ -0,0 +1,131 @@
+# 🦉 How to test Components 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Unit Tests](#unit-tests)
+
+## Overview
+
+It is a good practice to test applications and components to ensure that they
+behave as expected. There are many ways to test a user interface: manual
+testing, integration testing, unit testing, ...
+
+In this section, we will discuss how to write unit tests for components.
+
+## Unit Tests
+
+Writing unit tests for Owl components really depends on the testing framework
+used in a project. But usually, it involves the following steps:
+
+- create a test file: for example `SomeComponent.test.js`,
+- in that file, import the code for `SomeComponent`,
+- add a test case:
+  - create a real DOM element to use as test fixture,
+  - create a test environment
+  - create an instance of `SomeComponent`, mount it to the fixture
+  - interact with the component and assert some properties.
+
+To help with this, it is useful to have a `helper.js` file that contains some
+common utility functions:
+
+```js
+export function makeTestFixture() {
+  let fixture = document.createElement("div");
+  document.body.appendChild(fixture);
+  return fixture;
+}
+
+export function nextTick() {
+  let requestAnimationFrame = owl.Component.scheduler.requestAnimationFrame;
+  return new Promise(function(resolve) {
+    setTimeout(() => requestAnimationFrame(() => resolve()));
+  });
+}
+
+export function makeTestEnv() {
+    // application specific. It needs a way to load actual templates
+    const templates = ...;
+
+    return {
+        qweb: new QWeb(templates),
+        ..., // each service can be mocked here
+    };
+}
+```
+
+With such a file, a typical test suite for Jest will look like this:
+
+```js
+// in SomeComponent.test.js
+import { SomeComponent } from "../../src/ui/SomeComponent";
+import { nextTick, makeTestFixture, makeTestEnv} from '../helpers';
+
+
+//------------------------------------------------------------------------------
+// Setup
+//------------------------------------------------------------------------------
+let fixture: HTMLElement;
+let env: Env;
+
+beforeEach(() => {
+  fixture = makeTestFixture();
+  env = makeTestEnv();
+  // we set here the default environment for each component created in the test
+  Component.env = env;
+});
+
+afterEach(() => {
+  fixture.remove();
+});
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+describe("SomeComponent", () => {
+  test("component behaves as expected", async () => {
+    const props = {...}; // depends on the component
+    const comp = new SomeComponent(null, props);
+    await comp.mount(fixture);
+
+    // do some assertions
+    expect(...).toBe(...);
+
+    fixture.querySelector('button').click();
+    await nextTick();
+
+    // some other assertions
+    expect(...).toBe(...);
+  });
+});
+```
+
+Note that Owl does wait for the next animation frame to actually update the DOM.
+This is why it is necessary to wait with the `nextTick` (or other methods) to
+make sure that the DOM is up-to-date.
+
+It is sometimes useful to wait until Owl is completely done updating components
+(in particular, if we have a highly concurrent user interface). This next
+helper simply polls every 20ms the internal Owl task queue and returns a promise
+which resolves when it is empty:
+
+```js
+function afterUpdates() {
+  return new Promise((resolve, reject) => {
+    let timer = setTimeout(poll, 20);
+    let counter = 0;
+    function poll() {
+      counter++;
+      if (owl.Component.scheduler.tasks.length) {
+        if (counter > 10) {
+          reject(new Error("timeout"));
+        } else {
+          timer = setTimeout(poll);
+        }
+      } else {
+        resolve();
+      }
+    }
+  });
+}
+```

doc/learning/how_to_write_sfc.md

@@ -0,0 +1,52 @@
+# 🦉 How to write Single File Components 🦉
+
+It is very useful to group code by feature instead of by type of file. It makes
+it easier to scale application to larger size.
+
+To do so, Owl has two small helpers that make it easy to define a
+template or a stylesheet inside a javascript (or typescript) file: the
+[`xml`](../reference/tags.md#xml-tag) and [`css`](../reference/tags.md#css-tag)
+helper.
+
+This means that the template, the style and the javascript code can be defined in
+the same file. For example:
+
+```js
+const { Component } = owl;
+const { xml, css } = owl.tags;
+
+// -----------------------------------------------------------------------------
+// TEMPLATE
+// -----------------------------------------------------------------------------
+const TEMPLATE = xml/* xml */ `
+	<div class="main">
+		<Sidebar/>
+		<Content />
+	</div>`;
+
+// -----------------------------------------------------------------------------
+// STYLE
+// -----------------------------------------------------------------------------
+const STYLE = css/* css */ `
+  .main {
+    display: grid;
+    grid-template-columns: 200px auto;
+  }
+`;
+
+// -----------------------------------------------------------------------------
+// CODE
+// -----------------------------------------------------------------------------
+class Main extends Component {
+  static template = TEMPLATE;
+  static style = STYLE;
+  static components = { Sidebar, Content };
+
+  // rest of component...
+}
+```
+
+Note that the above example has an inline xml comment, just after the `xml` call.
+This is useful for some editor plugins, such as the VS Code addon
+`Comment tagged template`, which, if installed, add syntax highlighting to the
+content of the template string.

doc/learning/overview.md

@@ -0,0 +1,133 @@
+# 🦉 Quick Overview 🦉
+
+Owl components in an application are used to define a (dynamic) tree of components.
+
+```
+        Root
+        /   \
+       A     B
+      / \
+     C   D
+```
+
+**State:** each component can manage its own local state. It is a simple ES6
+class, there are no special rules:
+
+```js
+class Counter extends Component {
+  static template = xml`
+    <button t-on-click="increment">
+      Click Me! [<t t-esc="state.value"/>]
+    </button>`;
+
+  state = { value: 0 };
+
+  increment() {
+    this.state.value++;
+    this.render();
+  }
+}
+```
+
+The example above shows a component with a local state. Note that since there
+is nothing magical to the `state` object, we need to manually call the `render`
+function whenever we update it. This can quickly become annoying (and not
+efficient if we do it too much). There is a better way: using the `useState`
+hook, which transforms an object into a reactive version of itself:
+
+```js
+const { useState } = owl.hooks;
+
+class Counter extends Component {
+  static template = xml`
+    <button t-on-click="increment">
+      Click Me! [<t t-esc="state.value"/>]
+    </button>`;
+
+  state = useState({ value: 0 });
+
+  increment() {
+    this.state.value++;
+  }
+}
+```
+
+Note that the `t-on-click` handler can even be replaced by an inline statement:
+
+```xml
+    <button t-on-click="state.value++">
+```
+
+**Props:** sub components often needs some information from their parents. This
+is done by adding the required information to the template. This will then be
+accessible by the sub component in the `props` object. Note that there is an
+important rule here: the information contained in the `props` object is not
+owned by the sub component, and should never be modified.
+
+```js
+class Child extends Component {
+  static template = xml`<div>Hello <t t-esc="props.name"/></div>`;
+}
+
+class Parent extends Component {
+  static template = xml`
+    <div>
+        <Child name="'Owl'" />
+        <Child name="'Framework'" />
+    </div>`;
+  static components = { Child };
+}
+```
+
+**Communication:** there are multiple ways to communicate information between
+components. However, the two most important ways are the following:
+
+- from parent to children: by using `props`,
+- from a children to one of its parent: by triggering events.
+
+The following example illustrate both mechanisms:
+
+```js
+class OrderLine extends Component {
+  static template = xml`
+    <div t-on-click="add">
+        <div><t t-esc="props.line.name"/></div>
+        <div>Quantity: <t t-esc="props.line.quantity"/></div>
+    </div>`;
+
+  add() {
+    this.trigger("add-to-order", { line: props.line });
+  }
+}
+
+class Parent extends Component {
+  static template = xml`
+    <div t-on-add-to-order="addToOrder">
+        <OrderLine
+            t-foreach="orders"
+            t-as="line"
+            line="line" />
+    </div>`;
+  static components = { OrderLine };
+  orders = useState([
+    { id: 1, name: "Coffee", quantity: 0 },
+    { id: 2, name: "Tea", quantity: 0 },
+  ]);
+
+  addToOrder(event) {
+    const line = event.detail.line;
+    line.quantity++;
+  }
+}
+```
+
+In this example, the `OrderLine` component trigger a `add-to-order` event. This
+will generate a DOM event which will bubble along the DOM tree. It will then be
+intercepted by the parent component, which will then get the line (from the
+`detail` key) and then increment its quantity. See the page on [event handling](../reference/event_handling.md)
+for more details on how events work.
+
+Note that this example would have also worked if the `OrderLine` component
+directly modifies the `line` object. However, this is not a good practice: this
+only works because the `props` object received by the child component is reactive,
+so the child component is then coupled to the parents implementation.

doc/learning/quick_start.md

@@ -0,0 +1,411 @@
+# 🦉 How to start an Owl project 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Simple html file](#simple-html-file)
+- [With a static server](#with-a-static-server)
+- [Standard Javascript project](#standard-javascript-project)
+
+## Overview
+
+Each software project has its specific needs. Many of these needs can be solved
+with some tooling: `webpack`, `gulp`, css preprocessor, bundlers, transpilers, ...
+
+Because of that, it is usually not simple to just start a project. Some
+frameworks provide their own tooling to help with that. But then, you have to
+integrate and learn how these applications work.
+
+Owl is designed to be used with no tooling at all. Because of that, Owl can
+"easily" be integrated in a modern build toolchain. In this section, we will
+discuss a few different setups to start a project. Each of these setups has
+advantages and disadvantages in different situations.
+
+## Simple html file
+
+The simplest possible setup is the following: a simple javascript file with your
+code. To do that, let us create the following file structure:
+
+```
+hello_owl/
+  index.html
+  owl.js
+  app.js
+```
+
+The file `owl.js` can be downloaded from the last release published at
+[https://github.com/odoo/owl/releases](https://github.com/odoo/owl/releases). It
+is a single javascript file which export all Owl into the global `owl` object.
+
+Now, `index.html` should contain the following:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Hello Owl</title>
+    <script src="owl.js"></script>
+    <script src="app.js"></script>
+  </head>
+  <body></body>
+</html>
+```
+
+And `app.js` should look like this:
+
+```js
+const { Component } = owl;
+const { xml } = owl.tags;
+const { whenReady } = owl.utils;
+
+// Owl Components
+class App extends Component {
+  static template = xml`<div>Hello Owl</div>`;
+}
+
+// Setup code
+function setup() {
+  const app = new App();
+  app.mount(document.body);
+}
+
+whenReady(setup);
+```
+
+Now, simply loading this html file in a browser should display a welcome message.
+This setup is not fancy, but it is extremely simple. There are no tooling at
+all required. It can be slightly optimized by using the minified build of Owl.
+
+## With a static server
+
+The previous setup has a big disadvantage: the application code is located in a
+single file. Obviously, we could split it in several files and add multiple
+`<script>` tags in the html page, but then we need to make sure the script are
+inserted in the proper order, we need to export each file content in global
+variables and we lose autocompletion across files.
+
+There is a low tech solution to this issue: using native javascript modules.
+This however has a requirement: for security reasons, browsers will not accept
+modules on content served through the `file` protocol. This means that we need
+to use a static server.
+
+Let us start a new project with the following file structure:
+
+```
+hello_owl/
+  src/
+    app.js
+    index.html
+    main.js
+    owl.js
+```
+
+As previously, the file `owl.js` can be downloaded from the last release published at
+[https://github.com/odoo/owl/releases](https://github.com/odoo/owl/releases).
+
+Now, `index.html` should contain the following:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Hello Owl</title>
+    <script src="owl.js"></script>
+    <script src="main.js" type="module"></script>
+  </head>
+  <body></body>
+</html>
+```
+
+Not that the `main.js` script tag has the `type="module"` attribute. This means
+that the browser will parse the script as a module, and load all its dependencies.
+
+Here is the content of `app.js` and `main.js`:
+
+```js
+// app.js ----------------------------------------------------------------------
+const { Component } = owl;
+const { xml } = owl.tags;
+
+export class App extends Component {
+  static template = xml`<div>Hello Owl</div>`;
+}
+
+// main.js ---------------------------------------------------------------------
+import { App } from "./app.js";
+
+function setup() {
+  const app = new App();
+  app.mount(document.body);
+}
+
+owl.utils.whenReady(setup);
+```
+
+The `main.js` file import the `app.js` file. Note that the import statement has
+a `.js` suffix, which is important. Most text editor can understand this syntax
+and will provide autocompletion.
+
+Now, to execute this code, we need to serve the `src` folder statically. A low
+tech way to do that is to use for example the python `SimpleHTTPServer` feature:
+
+```
+$ cd src
+$ python -m SimpleHTTPServer 8022    # now content is available at localhost:8022
+```
+
+Another more "javascripty" way to do it is to create a `npm` application. To do
+that, we can add the following `package.json` file at the root of the project:
+
+```json
+{
+  "name": "hello_owl",
+  "version": "0.1.0",
+  "description": "Starting Owl app",
+  "main": "src/index.html",
+  "scripts": {
+    "serve": "serve src"
+  },
+  "author": "John",
+  "license": "ISC",
+  "devDependencies": {
+    "serve": "^11.3.0"
+  }
+}
+```
+
+We can now install the `serve` tool with the command `npm install`, and then,
+start a static server with the simple `npm run serve` command.
+
+## Standard Javascript project
+
+The previous setup works, and is certainly good for some usecases, including
+quick prototyping. However, it lacks some useful features, such as livereload,
+a test suite, or bundling the code in a single file.
+
+Each of these features, and many others, can be done in many different ways.
+Since it is really not trivial to configure such a project, we provide here an
+example that can be used as a starting point.
+
+Our standard Owl project has the following file structure:
+
+```
+hello_owl/
+  public/
+    index.html
+  src/
+    components/
+      App.js
+    main.js
+  tests/
+    components/
+      App.test.js
+    helpers.js
+  .gitignore
+  package.json
+  webpack.config.js
+```
+
+This project as a `public` folder, meant to contain all static assets, such as
+images and styles. The `src` folder has the javascript source code, and finally,
+`tests` contains the test suite.
+
+Here is the content of `index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Hello Owl</title>
+  </head>
+  <body></body>
+</html>
+```
+
+Note that there are no `<script>` tag here. They will be injected by webpack.
+Now, let's have a look at the javascript files:
+
+```js
+// src/components/App.js -------------------------------------------------------
+import { Component, tags, useState } from "@odoo/owl";
+
+const { xml } = tags;
+
+export class App extends Component {
+  static template = xml`<div t-on-click="update">Hello <t t-esc="state.text"/></div>`;
+  state = useState({ text: "Owl" });
+  update() {
+    this.state.text = this.state.text === "Owl" ? "World" : "Owl";
+  }
+}
+
+// src/main.js -----------------------------------------------------------------
+import { utils } from "@odoo/owl";
+import { App } from "./components/App";
+
+function setup() {
+  const app = new App();
+  app.mount(document.body);
+}
+
+utils.whenReady(setup);
+
+// tests/components/App.test.js ------------------------------------------------
+import { App } from "../../src/components/App";
+import { makeTestFixture, nextTick, click } from "../helpers";
+
+let fixture;
+
+beforeEach(() => {
+  fixture = makeTestFixture();
+});
+
+afterEach(() => {
+  fixture.remove();
+});
+
+describe("App", () => {
+  test("Works as expected...", async () => {
+    const app = new App();
+    await app.mount(fixture);
+    expect(fixture.innerHTML).toBe("<div>Hello Owl</div>");
+
+    click(fixture, "div");
+    await nextTick();
+    expect(fixture.innerHTML).toBe("<div>Hello World</div>");
+  });
+});
+
+// tests/helpers.js ------------------------------------------------------------
+import { Component } from "@odoo/owl";
+import "regenerator-runtime/runtime";
+
+export async function nextTick() {
+  return new Promise(function (resolve) {
+    setTimeout(() => Component.scheduler.requestAnimationFrame(() => resolve()));
+  });
+}
+
+export function makeTestFixture() {
+  let fixture = document.createElement("div");
+  document.body.appendChild(fixture);
+  return fixture;
+}
+
+export function click(elem, selector) {
+  elem.querySelector(selector).dispatchEvent(new Event("click"));
+}
+```
+
+Finally, here is the configuration files `.gitignore`, `package.json` and
+`webpack.config.js`:
+
+```
+node_modules/
+package-lock.json
+dist/
+```
+
+```json
+{
+  "name": "hello_owl",
+  "version": "0.1.0",
+  "description": "Demo app",
+  "main": "src/index.html",
+  "scripts": {
+    "test": "jest",
+    "build": "webpack --mode production",
+    "dev": "webpack-dev-server --mode development"
+  },
+  "author": "Someone",
+  "license": "ISC",
+  "devDependencies": {
+    "@babel/core": "^7.8.4",
+    "@babel/plugin-proposal-class-properties": "^7.8.3",
+    "babel-jest": "^25.1.0",
+    "babel-loader": "^8.0.6",
+    "babel-plugin-transform-es2015-modules-commonjs": "^6.26.2",
+    "html-webpack-plugin": "^3.2.0",
+    "jest": "^25.1.0",
+    "regenerator-runtime": "^0.13.3",
+    "serve": "^11.3.0",
+    "webpack": "^4.41.5",
+    "webpack-cli": "^3.3.10",
+    "webpack-dev-server": "^3.10.2"
+  },
+  "dependencies": {
+    "@odoo/owl": "^1.0.4"
+  },
+  "babel": {
+    "plugins": ["@babel/plugin-proposal-class-properties"],
+    "env": {
+      "test": {
+        "plugins": ["transform-es2015-modules-commonjs"]
+      }
+    }
+  },
+  "jest": {
+    "verbose": false,
+    "testRegex": "(/tests/.*(test|spec))\\.js?$",
+    "moduleFileExtensions": ["js"],
+    "transform": {
+      "^.+\\.[t|j]sx?$": "babel-jest"
+    }
+  }
+}
+```
+
+```js
+const path = require("path");
+const HtmlWebpackPlugin = require("html-webpack-plugin");
+
+const host = process.env.HOST || "localhost";
+
+module.exports = function (env, argv) {
+  const mode = argv.mode || "development";
+  return {
+    mode: mode,
+    entry: "./src/main.js",
+    output: {
+      filename: "main.js",
+      path: path.resolve(__dirname, "dist"),
+    },
+    module: {
+      rules: [
+        {
+          test: /\.jsx?$/,
+          loader: "babel-loader",
+          exclude: /node_modules/,
+        },
+      ],
+    },
+    resolve: {
+      extensions: [".js", ".jsx"],
+    },
+    devServer: {
+      contentBase: path.resolve(__dirname, "public/index.html"),
+      compress: true,
+      hot: true,
+      host,
+      port: 3000,
+      publicPath: "/",
+    },
+    plugins: [
+      new HtmlWebpackPlugin({
+        inject: true,
+        template: path.resolve(__dirname, "public/index.html"),
+      }),
+    ],
+  };
+};
+```
+
+With this setup, we can now use the following script commands:
+
+```
+npm run build # build the full application in prod mode in dist/
+
+npm run dev # start a dev server with livereload
+
+npm run test # run the jest test suite
+```

doc/miscellaneous/comparison.md

@@ -0,0 +1,345 @@
+# Comparison with Vue/React
+
+OWL, React and Vue have the same main feature: they allow developers to build
+declarative user interfaces. To do that, all these frameworks uses a virtual dom. However, there are still obviously many differences.
+
+In this page, we try to highlight some of these differences. Obviously, a lot of
+effort was done to be fair. However, if you disagree with some of the points
+discussed, feel free to open an issue/submit a PR to correct this text.
+
+## Content
+
+- [Size](#size)
+- [Class Based](#class-based)
+- [Tooling/Build Step](#toolingbuild-step)
+- [Templating](#templating)
+- [Asynchronous rendering](#asynchronous-rendering)
+- [Reactiveness](#reactiveness)
+- [State Management](#state-management)
+- [Hooks](#hooks)
+
+## Size
+
+OWL is intended to be small and to work at a slightly lower level of abstraction
+than React and Vue. Also, jQuery is not the same kind of framework, but it is interesting to compare.
+
+| Framework                | Size (minified, gzipped) |
+| ------------------------ | ------------------------ |
+| OWL                      | 18kb                     |
+| Vue + VueX               | 30kb                     |
+| Vue + VueX + Vue Router  | 39kb                     |
+| React + ReactDOM + Redux | 40kb                     |
+| jQuery                   | 30kb                     |
+
+Note that those comparisons are not entirely fair, because we do not compare
+the same exact set of features. For example, VueX and Vue Router support more
+advanced use cases.
+
+## Class Based
+
+Both React and Vue moved away from defining components with classes. They prefer
+a more functional approach, in particular, with the new `hooks` mechanisms.
+
+This has some advantages and disadvantages. But the end result is that React
+and Vue both offers multiple different ways of defining new components. In
+contrast, Owl has only one mechanism: class-based components. We believe that Owl
+components are fast enough for all our usecases, and making it as simple as
+possible for developers is more valuable (for us).
+
+Also, functions or class based components are more than just syntax. Functions
+comes with a mindset of composition and class are about inheritance. Clearly,
+both of these are important mechanisms for reusing code. Also, one does not
+exclude the other.
+
+It certainly looks like the world of UI frameworks is moving toward composition,
+for many very good reasons. Owl is still good at composition (for example,
+Owl supports slots, which is the primary mechanism to make generic reusable
+components). But it can also use inheritance (and this is very important since
+templates can also be inherited with `xpaths` transformations).
+
+## Tooling/Build step
+
+OWL is designed to be easy to use in a standalone way. For various reasons,
+Odoo does not want to rely on standard web tools (such as webpack), and OWL can
+be used by simply adding a script tag to a page.
+
+```html
+<script src="owl.min.js" />
+```
+
+In comparison, React encourages using JSX, which necessitate a build step, and
+most Vue applications uses single file components, which also necessitate a build step.
+
+On the flipside, external tooling may make it harder to use in some case, but it
+also brings a lot of benefits. And React/Vue have both a large ecosystem.
+
+Note that since Owl is not dependant on any external tool nor libraries, it is
+very easy to integrate into any build toolchain. Also, since we cannot rely on
+additional tools, we made a lot of effort to make the most of the web platform.
+
+For example, Owl uses the standard `xml` parser that comes with every browser.
+Because of that, Owl did not have to write its own template parser. Another
+example is the [`xml`](../reference/tags.md#xml-tag) tag helper function, which makes use of
+native template literals to allow in a natural way to write `xml` templates
+directly in the javascript code. This can be easily integrated with editor
+plugins to have autocompletion inside the template.
+
+## Templating
+
+OWL uses its own QWeb engine, which compiles templates on the
+frontend, as they are needed. This is extremely convenient for our use case, in
+particular because templates are described in XML files, and can be modified by
+XPaths. Since Odoo is at its heart a modular application, this is an important
+feature for us.
+
+```xml
+<div>
+  <button t-on-click="increment">Click Me! [<t t-esc="state.value"/>]</button>
+</div>
+```
+
+Vue is actually kind of similar. Its template language is kind of close to QWeb,
+with the `v` replaced by the `t`. However, it is also more fully featured. For
+example, Vue templates have slots, or event modifiers. A large difference is that
+most Vue applications will need to be built ahead of time, to compile the templates
+into javascript functions. Note that Vue has a separate build which includes the
+template compiler.
+
+In contrast, most React applications do not use a templating language, but write
+some JSX code, which is precompiled into plain JavaScript by a build step. This
+example is done with the (kind of outdated) React class system:
+
+```jsx
+class Clock extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.props.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+```
+
+This has the advantage of having the full power of Javascript, but is less
+structured than a template language. Note that the tooling is quite impressive:
+there is a syntax highlighter for jsx here on github!
+
+By comparison, here is the equivalent Owl component, written with the
+[`xml`](../reference/tags.md#xml-tag) tag helper:
+
+```js
+class Clock extends Component {
+  static template = xml`
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {props.date.toLocaleTimeString()}.</h2>
+      </div>
+    `;
+}
+```
+
+## Asynchronous Rendering
+
+This is actually a big difference between OWL and React/Vue: components in OWL
+are totally asynchronous. They have two asynchronous hooks in their lifecycle:
+
+- `willStart` (before the component starts rendering)
+- `willUpdateProps` (before new props are set)
+
+Both these methods can be implemented and return a promise. The rendering will
+then wait for these promises to be completed before patching the DOM. This is
+useful for some use cases: for example, a component may want to fetch an external
+library (a calendar component may need a specialized calendar rendering library),
+in its willStart hook.
+
+```javascript
+class MyCalendarComponent extends owl.Component {
+    ...
+
+    willStart() {
+        return utils.lazyLoad('static/libs/fullcalendar/fullcalendar.js');
+    }
+    ...
+}
+```
+
+This may be dangerous (to stop the rendering waiting for the network), but it is
+extremely powerful as well, as demonstrated by the Odoo Web Client.
+
+Lazy loading static libraries can obviously be done with React/Vue, but it is
+more convoluted. For example, in Vue, you need to use a dynamic import keyword
+that needs to be transpiled at build time in order for the component to be loaded
+asynchronously (see [the documentation](https://vuejs.org/v2/guide/components-dynamic-async.html#Async-Components)).
+
+## Reactiveness
+
+React has a simple model: whenever the state changes, it is
+replaced with a new state (via the `setState` method). Then, the DOM is patched.
+This is simple, efficient, and a little bit awkward to write.
+
+Vue is a little bit different: it replace magically the properties in the state
+by getters/setters. With that, it can notify components whenever the state that
+they read was changed.
+
+Owl is closer to vue: it also tracks magically the state properties, but it does
+only increment an internal counter whenever it changes. Note that it is done
+with a `Proxy`, which means that it is totally transparent to the developers.
+Adding new keys is supported. Once any part of the state has been changed, a
+rendering is scheduled in the next microtask tick (promise queue).
+
+## State Management
+
+Managing the state of an application is a tricky issue. Many solutions have
+been proposed these last few years. It also depends on the kind of application we
+are talking about. A small application may not need much more than a simple
+object to contain its state.
+
+However, there are some common solutions for React and Vue: redux and vuex.
+Both of them are a centralized store that own the state, and they dictate how
+the state can be mutated.
+
+**Redux**
+
+In Redux, the state is mutated by reducers. Reducers are functions
+that modify the state by returning a different object:
+
+```javascript
+  ...
+  switch (action.type) {
+    case ADD_TODO: {
+      const { id, content } = action.payload;
+      return {
+        ...state,
+        allIds: [...state.allIds, id],
+        byIds: {
+          ...state.byIds,
+          [id]: {
+            content,
+            completed: false
+          }
+        }
+      };
+    }
+```
+
+This is a little bit awkward to write, but this allows the component system to
+check if a part of the state was changed. This is exactly what is done by the
+`connect` function: it create a _connected_ component, which is subscribed to
+the state and triggers a rerender if some part of the state was modified.
+
+**VueX**
+
+VueX is based on a different principle: the state is mutated through
+some special functions (the mutations), which modify the state in place:
+
+```javascript
+    function ({state}, payload) {
+        const { id, content } = payload;
+        const message = {id, content, completed: false};
+        state.messages.push(message)
+    }
+```
+
+This is simpler, but there is a little bit more happening behind the scene:
+each key from the state is silently replaced by getters and setters, and VueX
+keeps track of who get data, and retrigger a render when it was changed.
+
+**Owl**
+
+Owl store is a little bit like a mix of redux and vuex: it has actions (but not
+mutations), and like VueX, it keeps track of the state changes. However, it does
+not notify a component when the state changes. Instead, components need to connect
+to the store like in redux, with the `useStore` hook (see the [store documentation](../reference/store.md#connecting-a-component)).
+
+```javascript
+const actions = {
+  increment({ state }, val) {
+    state.counter.value += val;
+  },
+};
+
+const state = {
+  counter: { value: 0 },
+};
+const store = new owl.Store({ state, actions });
+
+class Counter extends Component {
+  static template = xml`
+      <button t-name="Counter" t-on-click="dispatch('increment')">
+        Click Me! [<t t-esc="counter.value"/>]
+      </button>`;
+  counter = useStore((state) => state.counter);
+  dispatch = useDispatch();
+}
+
+Counter.env.store = store;
+const counter = new Counter();
+```
+
+## Hooks
+
+[Hooks](https://reactjs.org/docs/hooks-intro.html#motivation) recently took over
+the React world. They solve a lot of seemingly unconnected problems: attach
+reusable behavior to a component, in a composable way, extract stateful logic
+from a component or reuse stateful logic between component, without changing your
+component hierarchy.
+
+Here is an example of the React `useState` hook:
+
+```js
+import React, { useState } from "react";
+
+function Example() {
+  // Declare a new state variable, which we'll call "count"
+  const [count, setCount] = useState(0);
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>Click me</button>
+    </div>
+  );
+}
+```
+
+Because of the way React designed the hooks API, they only work for functional
+components. But in that case, they really are powerful. Every major React library
+is in the process of redesigning their API with hooks (for example,
+[Redux](https://react-redux.js.org/next/api/hooks)).
+
+Vue 2 does not have hooks, but the Vue project is working on its next version,
+which will feature its new [composition API](https://vue-composition-api-rfc.netlify.com/).
+This work is based on the new ideas introduced by React hooks.
+
+From the way React and Vue introduce their hooks, it may look like hooks are not
+compatible with class components. However, this is not the case, as shown by
+Owl [hooks](../reference/hooks.md). They are inspired by both React and Vue. For example,
+the `useState` hook is named after React, but its API is closer to the `reactive`
+Vue hook.
+
+Here is what the `Counter` example above look like in Owl:
+
+```js
+import { Component, Owl } from "owl";
+import { xml } from "owl/tags";
+
+class Example extends Component {
+  static template = xml`
+      <div>
+        <p>You clicked {count.value} times</p>
+        <button t-on-click="increment">Click me</button>
+      </div>`;
+
+  count = useState({ value: 0 });
+
+  increment() {
+    this.state.value++;
+  }
+}
+```
+
+Since the Owl framework had hooks from early in its life, its main APIs
+are designed to be interacted with hooks from the start. For example, the
+`Context` and `Store` abstractions.

doc/miscellaneous/rendering.md

@@ -0,0 +1,32 @@
+# 🦉 Rendering Pipeline 🦉
+
+We explain here how Owl is designed, from the perspective of its rendering
+pipeline.
+
+Warning: these notes are technical by nature, and intended for people working
+on Owl (or interested in understanding its design).
+
+## Overview
+
+A rendering occurs in two phases:
+
+- virtual rendering: this generates the virtual dom in memory, asynchronously
+- patch: applies a virtual tree to the screen (synchronously)
+
+There are several classes involved in a rendering:
+
+- components
+- a scheduler
+- fibers: small objects containing some metadata, associated with a rendering of
+  a specific component
+
+Components are organized in a dynamic component tree, visible in the user
+interface. Whenever a rendering is initiated in a component `C`:
+
+- a fiber is created on `C` with the rendering props information
+- the virtual rendering phase starts on C (will asynchronously render all the
+  child components)
+- the fiber is added to the scheduler, which will poll continuously, every
+  animation frame, if the fiber is done
+- once it is done, the scheduler will call the task callback, which will apply
+  the patch (if it was not cancelled in the meantime).

doc/miscellaneous/vdom.md

@@ -0,0 +1,18 @@
+# 🦉 VDom 🦉
+
+Owl is a declarative component system: we declare the structure of the component
+tree, and Owl will translate that to a list of imperative operations. This
+translation is done by a virtual dom. This is the low level layer of Owl, most
+developer will not need to call directly the virtual dom functions.
+
+The main idea behind a virtual dom is to keep a in-memory representation of the
+DOM (called a virtual node), and whenever some change is needed, to regenerate
+a new representation, compute the difference between the old and the new, then
+apply the changes.
+
+`vdom` exports two functions:
+
+- `h`: create a new virtual node
+- `patch`: compare two virtual nodes, and apply the difference.
+
+Note: Owl's virtual dom is a fork of [snabbdom](https://github.com/snabbdom/snabbdom).

doc/miscellaneous/why_owl.md

@@ -0,0 +1,180 @@
+# 🦉 Why Owl ? 🦉
+
+The common wisdom is that one should not reinvent the wheel, because that would
+waste effort and resources. It is certainly true in many cases. A javascript
+framework is a considerable investment, so it is quite logical to ask the question:
+why did Odoo decide to make OWL instead of using a standard/well known framework,
+such as React or Vue?
+
+As you might expect, the answer to that question is not simple. But most of the
+reasons discussed in this page are a consequence from a single fact: Odoo is
+extremely modular.
+
+This means, for example, that the core parts of Odoo are not aware, before runtime,
+of what files will be loaded/executed, or what will be the state of the UI. Because
+of that, Odoo cannot rely on a standard build toolchain. Also, this implies that
+the core parts of Odoo need to be extremely generic. In other words, Odoo is not
+really an application with a user interface. It is an application which generates
+a dynamic user interface. And most frameworks are not up to the task.
+
+Betting on Owl was not an easy choice to make, because there certainly are a lot
+of conflicting needs that we want to carefully balance. Choosing anything other
+than a well known framework is bound to be controversial. This page will explain
+some of the reason why we still believe that building Owl is a worthwile
+endeavour.
+
+## Strategy
+
+It is true that we want to keep control of our technology, in the sense that we
+do not want to depend on Facebook or Google, or any other large (or small)
+company. If they decide to change their license, or to go in a direction that
+will not work for us, this may be a problem. This is even more true because
+Odoo is not a conventional javascript application, and our needs are probably
+quite different as most other applications.
+
+## Class components
+
+It is clear that the biggest frameworks are moving away from class components.
+There is an implicit assumption that class components are terrible, and that
+functional programming is the way to go. React even goes as far as to say that
+classes are confusing for developers.
+
+While there is some truth to that, and to the fact that composition is certainly
+a good mechanism for code reuse, we believe that classes and inheritance are
+important tools.
+
+Sharing code between generic components with inheritance is the way Odoo built
+its web client. And it is clear that inheritance is not the root of all evils.
+It is often a perfectly simple and appropriate solution. What matter most is
+the architectural decisions.
+
+Also, Odoo has another specific use out of class components: each method of a
+class provides an extension point for addons. This may not be a clean architecture
+pattern, but it is a pragmatic decision that served Odoo well: classes are
+sometimes monkey-patched to add behaviour from the outside. A little bit like
+mixins, but from the outside.
+
+Using React or Vue would make it significantly harder to monkey patch components,
+because a lot of the state is hidden in their internals.
+
+## Tooling
+
+React or Vue have a huge community, and a lot of effort have been made into their
+tooling. This is wonderful, but at the same time, a pretty big issue for Odoo:
+since the assets are totally dynamic (and could change whenever the user install
+or remove an addon), we need to have all that kind of tooling on the production
+servers. This is certainly not ideal.
+
+Also, this makes it very complicated to setup Vue or React tools: Odoo code is
+not a simple file that import other files. It changes all the time, assets
+are bundled differently in different contexts. This is the reason why Odoo has
+its own module system, which are resolve at runtime, by the browser. The
+dynamic nature of Odoo means that we often need to delay work as late as possible
+(in other word, we want a JIT user interface!)
+
+Our ideal framework has minimal (mandatory) tooling, which makes it easier to
+deploy. Using React without JSX, or Vue without vue file is not very appealing.
+
+At the same time, Owl is designed to solve this issue: it compiles templates
+by the browser, it doesn't need much code for that, since we use the XML parser
+built into each browser. Owl works with or without any additional tooling. It
+can use template strings to write single file component, and is easy to integrate
+in any html page, with a simple `<script>` tag.
+
+## Template based
+
+Odoo stores template as XML document in a database. This is very powerful, since
+this allow the use of xpaths to customize other templates. This is a very
+important feature of odoo, and one of the key to Odoo modularity.
+
+Because of that, we still expect to write our templates in an XML document.
+Weirdly enough, no major framework uses XML to store templates, even though it
+is extremely convenient.
+
+So, using React or Vue means that we need to make a template compiler. For React,
+that would be a compiler that would take a QWeb template, and convert it to a
+React render function. For Vue, it would convert it to a Vue template. Then
+we need to bundle the vue template compiler as well.
+
+Not only this would be complex (compiling a templating language into another is
+not an easy task), but it would negatively impact the developer experience as
+well. Writing Vue or React components in a QWeb template would certainly be
+awkward, and very confusing.
+
+## Developer Experience
+
+This brings us to the following point: developer experience. We see this choice
+as an investment for the future, and we want to make onboarding developer as
+easy as possible.
+
+While many javascript professionals clearly think that react/vue is not difficult
+(which is true to some extent), it is alsy true that many non js specialists are
+overwhelmed with the frontend world: functional component, hooks, and many other
+fancy words. Also, what is available in the compilation context may be difficult,
+there is a lot of black magic going on in pretty much every framework. Vue
+somehow join various namespaces into one, under the hood, and add various internal
+keys. Svelte transform the code. React require that state transformations are
+deep, and not shallow.
+
+Owl is trying very hard to have a simple and familiar API. It uses classes. Its
+reactivity system is explicit, not implicit. The scoping rules are obvious. In
+case of doubt, we err on the side of not implementing a feature.
+
+It is certainly different from React or Vue, but at the same time, kind of
+familiar for experienced developers.
+
+## JIT compilation
+
+There is also a clear trend in the frontend world to compile code
+as much as possible ahead of time. Most frameworks will compile templates ahead
+of time. And now Svelte is trying to compile the JS code away, so it can remove
+itself from the bundle.
+
+This is certainly reasonable for many usecases. However, this is not what Odoo
+needs: Odoo will fetch templates from the database and need to compile them only
+at the last possible moment, so we can apply all necessary xpaths.
+
+Even more: Odoo needs to be able to generate (and compile) templates at runtime.
+Currently, Odoo form views interpret a xml description. But the form view code
+then needs to do a lot of complicated operations. With Owl, we will be able to
+transform a view description into a QWeb template, then compile that and use it
+immediately.
+
+## Reactivity
+
+There are other design choices that we feel are not optimal in other frameworks.
+For example, the reactivity system. We like the way Vue did it, but it has a
+flaw: it is not really optional. There is actually a way to opt out of the reactivity
+system by freezing the state, but then, it is freezed.
+
+And there certainly are situations where we need a state, which is not readonly,
+and not observed. For example, imagine a spreadsheet component. It may have a
+very large internal state, and it knows exactly when it needs to be rendered
+(basically, whenever the user perform some action). Then, observing its state
+is a net performance loss, both for the CPU and the memory.
+
+## Concurrency
+
+Many applications are happy to simply display a spinner whenever a new asynchronous
+action is performed, but Odoo want a different user experience: most asynchronous
+state changes are not displayed until ready. This is sometimes called a concurrent
+mode: the UI is rendered in memory, and displayed only when it is ready (and
+only if it has not been cancelled by subsequent user actions).
+
+React has now an experimental concurrent mode, but it was not ready when Owl
+started. Vue has not really an equivalent API (suspense is not what we need).
+
+Also, React concurrent mode is complex to use. Concurrency was one of the rare
+strong point of the former Odoo js framework (widgets), and we feel that Owl has
+now a very strong concurrent mode, which is simple and powerful at the same time.
+
+## Conclusion
+
+This lengthy discussion showed that there are many small and not so small reasons
+that current standard frameworks are not tailored to our needs. It is perfectly
+fine, because they each chose a different set of tradeoffs.
+
+However, we feel that there is still room in the framework world for something
+that is different. For a framework that make choices compatible with Odoo.
+
+And that is why we built Owl 🦉.

doc/observer.md

@@ -1,54 +0,0 @@
-# 🦉 Observer 🦉
-
-Owl need to be able to react to state changes. For example, whenever the state
-of a component is changed, we need to rerender it. To help with that, we have
-an Observer class. Its job is to observe some object state, and react to any
-change. To do that, it recursively replace all keys of the observed state by
-getters and setters.
-
-For example, this code will display `update` in the console:
-
-```javascript
-const observer = new owl.Observer();
-observer.notifyCB = () => console.log("update");
-observer.observe(obj);
-
-const obj = { a: { b: 1 } };
-obj.a.b = 2;
-```
-
-## Technical Limitations
-
-Since the observer uses getters and setters, it is actually unable to react to
-changes in two situations:
-
-- adding a key to an object:
-
-  ```javascript
-  const observer = new owl.Observer();
-  const obj = { a: 1 };
-  observer.observe(obj);
-  obj.b = 2; // will do nothing
-  ```
-
-  In that case, we need a way to tell the observer that something happened.
-  This can be done by using the `set` method:
-
-  ```javascript
-  observer.set(obj, "b", 2);
-  ```
-
-- modifying an array by setting a new value at a given index:
-
-  ```javascript
-  const observer = new owl.Observer();
-  const obj = { todos: [{ id: 1, text: "todo" }] };
-  observer.observe(obj);
-  obj[0] = { id: 2, text: "othertodo" }; // will do nothing, and obj[0] is not observed
-  ```
-
-  In that case, the solution is the same, we can simply use the `set` method:
-
-  ```javascript
-  observer.set(obj, 0, { id: 2, text: "othertodo" });
-  ```

doc/quick_start.md

@@ -1,101 +0,0 @@
-# 🦉 Quick Start 🦉
-
-## Static server
-
-Let us assume that we have a static server running somewhere. We could then
-simply add an html page with a few extra files.
-
-### HTML and CSS
-
-In a file `index.html`:
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>My OWL App</title>
-    <link href="app.css" rel="stylesheet" />
-    <script src="owl-X.Y.Z.js"></script>
-  </head>
-  <body>
-    <div id="main"></div>
-    <script src="app.js" type="module"></script>
-  </body>
-</html>
-```
-
-In `app.css`:
-
-```css
-button {
-  color: darkred;
-  font-size: 30px;
-  width: 220px;
-}
-```
-
-Also, let's not forget to add a release of OWL (`owl-X.Y.Z.js`)
-
-### XML
-
-In `templates.xml`:
-
-```xml
-<templates>
-   <button t-name="clickcounter" t-on-click="increment">
-      Click Me! [<t t-esc="state.value"/>]
-    </button>
-</templates>
-```
-
-### JS
-
-To build an application (or a sub-part of an application), we need two things:
-
-- an environment: it is the global context in which we are working. It needs to
-  contain a QWeb instance (preloaded with templates), and anything else that we
-  need. In practice, it could context some user session information, some
-  configuration keys (for example, isMobile = true/false if we are in mobile mode).
-
-- a description of the user interface: there should be a root widget, which can
-  have sub widgets
-
-Here are a few steps that we may take to get started:
-
-- get the templates
-- create a qweb engine, with the templates
-- create an environment
-- create an instance of the root widget
-- mount the root widget to a DOM element
-
-Let us now add the javascript to make it work, in `app.js`:
-
-```javascript
-class ClickCounter extends owl.Component {
-  constructor() {
-    super(...arguments);
-    this.template = "clickcounter";
-    this.state = { value: 0 };
-  }
-
-  increment() {
-    this.state.value++;
-  }
-}
-
-//------------------------------------------------------------------------------
-// Application initialization
-//------------------------------------------------------------------------------
-async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
-  const env = {
-    qweb: new owl.QWeb(templates)
-  };
-  const counter = new ClickCounter(env);
-  const target = document.getElementById("main");
-  await counter.mount(target);
-}
-
-start();
-```

doc/qweb.md

@@ -1,594 +0,0 @@
-# 🦉 QWeb 🦉
-
-## Content
-
-- [Overview](#overview)
-- [QWeb Engine](#qweb-engine)
-- [QWeb Specification](#qweb-specification)
-
-  - [Static html nodes](#static-html-nodes)
-  - [`t-esc` directive](#t-esc-directive)
-  - [`t-raw` directive](#t-raw-directive)
-  - [`t-set` directive](#t-set-directive)
-  - [`t-if` directive](#t-if-directive)
-  - [Expression evaluation](#expression-evaluation)
-  - [Dynamic attributes (`t-att` and `t-attf` directives)](#dynamic-attributes-t-att-and-t-attf-directives)
-  - [`t-attf` directive (dynamic attributes)](#t-att-directive-dynamic-attributes)
-  - [`t-call` directive (sub templates)](#t-call-directive-sub-templates)
-
-- [JS/OWL Specific Extensions](#jsowl-specific-extensions)
-
-  - [`t-on` directive](#t-on-directive)
-  - [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-directive)
-  - [`t-mounted` directive](#t-mounted-directive)
-  - [Debugging (`t-debug` and `t-log`)](#debugging-t-debug-and-t-log)
-  - [White spaces](#white-spaces)
-  - [Root nodes](#root-nodes)
-
-## Overview
-
-[QWeb](https://www.odoo.com/documentation/12.0/reference/qweb.html) is the primary templating engine used by Odoo. It is based on the XML format, and used
-mostly to generate html. In OWL, QWeb templates are compiled into functions that
-generate a virtual dom representation of the html.
-
-Template directives are specified as XML attributes prefixed with `t-`, for instance `t-if` for conditionals, with elements and other attributes being rendered directly.
-
-To avoid element rendering, a placeholder element `<t>` is also available, which executes its directive but doesn’t generate any output in and of itself.
-
-The QWeb implementation in the OWL project is slightly different. It compiles
-templates into functions that output a virtual DOM instead of a string. This is
-necessary for the component system. In addition, it has a few extra directives
-(see [OWL Specific Extensions](#owlspecificextensions))
-
-## QWeb Engine
-
-This section is about the javascript code that implements the `QWeb` specification.
-Owl exports a `QWeb` class in `owl.QWeb`. To use it, it just needs to be
-instantiated:
-
-```js
-const qweb = new owl.QWeb();
-```
-
-It's API is quite simple:
-
-- **`constructor(data)`**: constructor. Takes an optional string to add initial
-  templates (see `addTemplates` for more information on format of the string).
-
-  ```js
-  const qweb = new owl.QWeb(TEMPLATES);
-  ```
-
-- **`addTemplate(name, xmlStr)`**: add a specific template.
-
-  ```js
-  qweb.addTemplate("mytemplate", "<div>hello</div>");
-  ```
-
-- **`addTemplates(xmlStr)`**: add a list of templates (identified by `t-name`
-  attribute).
-
-  ```js
-  const TEMPLATES = `
-    <templates>
-      <div t-name="App" class="main">main</div>
-      <div t-name="OtherWidget">other widget</div>
-    </templates>`;
-  qweb.addTemplates(TEMPLATES);
-  ```
-
-- **`render(name, context, extra)`**: renders a template. This returns a `vnode`,
-  which is a virtual representation of the DOM (see [vdom doc](vdom.md)).
-
-  ```js
-  const vnode = qweb.render("App", widget);
-  ```
-
-## QWeb Specification
-
-We define in this section the specification of how `QWeb` templates should be
-rendered.
-
-### Static html nodes
-
-Normal, regular html nodes are rendered into themselves:
-
-```xml
-  <div>hello</div> <!–– rendered as itself ––>
-```
-
-### `t-esc` directive
-
-The `t-esc` directive is necessary whenever you want to add a dynamic text
-expression in a template. The text is escaped to avoid security issues.
-
-```xml
-<p><t t-esc="value"/></p>
-```
-
-rendered with the value `value` set to `42` in the rendering context yields:
-
-```html
-<p>42</p>
-```
-
-### `t-raw` directive
-
-The `t-raw` directive is almost the same as `t-esc`, but without the escaping.
-This is mostly useful to inject a raw html string somewhere. Obviously, this
-is unsafe to do in general, and should only be used for strings known to be safe.
-
-```xml
-<p><t t-esc="value"/></p>
-```
-
-rendered with the value `value` set to `<span>foo</span>` in the rendering context yields:
-
-```html
-<p><span>foo</span></p>
-```
-
-### `t-set` directive
-
-QWeb allows creating variables from within the template, to memoize a computation (to use it multiple times), give a piece of data a clearer name, ...
-
-This is done via the `t-set` directive, which takes the name of the variable to create. The value to set can be provided in two ways:
-
-1. a `t-value` attribute containing an expression, and the result of its
-   evaluation will be set:
-
-   ```xml
-   <t t-set="foo" t-value="2 + 1"/>
-   <t t-esc="foo"/>
-   ```
-
-   will print `3`. Note that the evaluation is done at rendering time, not at
-   compilte time.
-
-2. if there is no `t-value` attribute, the node’s body is saved and its value is
-   set as the variable’s value:
-
-   ```xml
-   <t t-set="foo">
-       <li>ok</li>
-   </t>
-   <t t-esc="foo"/>
-   ```
-
-   will generate `&lt;li&gt;ok&lt;/li&gt;` (the content is escaped as we used the `t-esc` directive)
-
-The `t-set` directive acts like a regular variable in most programming language.
-It is lexically scoped (inner nodes are sub scopes), can be shadowed, ...
-
-### `t-if` directive
-
-The `t-if` directive is useful to conditionally render something. It evaluates
-the expression given as attribute value, and then acts accordingly.
-
-```xml
-<div>
-    <t t-if="condition">
-        <p>ok</p>
-    </t>
-</div>
-```
-
-The element is rendered if the condition (evaluated with the current rendering
-context) is true:
-
-```xml
-<div>
-    <p>ok</p>
-</div>
-```
-
-but if the condition is false it is removed from the result:
-
-```xml
-<div>
-</div>
-```
-
-The conditional rendering applies to the bearer of the directive, which does not
-have to be `<t>`:
-
-```xml
-<div>
-    <p t-if="condition">ok</p>
-</div>
-```
-
-will give the same results as the previous example.
-
-Extra conditional branching directives `t-elif` and `t-else` are also available:
-
-```xml
-<div>
-    <p t-if="user.birthday == today()">Happy bithday!</p>
-    <p t-elif="user.login == 'root'">Welcome master!</p>
-    <p t-else="">Welcome!</p>
-</div>
-```
-
-### Expression evaluation
-
-It is useful to explain the various rules that applies on QWeb expressions. These
-expressions are strings that will be converted to a javascript expression at
-compile time.
-
-1. it should be a simple expression which returns a value. It cannot be a statement.
-
-   ```xml
-   <div><p t-if="1 + 2 === 3">ok</p></div>
-   ```
-
-   is valid, but the following is not valid:
-
-   ```xml
-   <div><p t-if="console.log(1)">NOT valid</p></div>
-   ```
-
-2. it can use anything in the rendering context:
-
-   ```xml
-   <p t-if="user.birthday == today()">Happy bithday!</p>
-   ```
-
-   is valid, and will read the `user` object from the context, and call the
-   `today` function.
-
-3. it can use a few special operators to avoid using symbols such as `<`, `>`,
-   `&` or `|`. This is useful to make sure that we still write valid XML.
-
-   | Word  | will be replaced by |
-   | ----- | ------------------- |
-   | `and` | `&&`                |
-   | `or`  | `\|\|`              |
-   | `gt`  | `>`                 |
-   | `gte` | `>=`                |
-   | `lt`  | `<`                 |
-   | `lte` | `<=`                |
-
-   So, one can write this:
-
-   ```xml
-   <div><p t-if="10 + 2 gt 5">ok</p></div>
-   ```
-
-### Dynamic attributes (`t-att` and `t-attf` directives)
-
-One can use the `t-att-` directive to add dynamic attributes. Its main use is to
-evaluate an expression (at rendering time) and bind an attribute to its result:
-
-For example, if we have `id` set to 32 in the rendering context,
-
-```xml
-<div t-att-data-action-id="id"/> <!-- result: <div data-action-id="32"></div> -->
-```
-
-If an expression evaluates to a falsy value, it will not be set at all:
-
-```xml
-<div t-att-foo="false"/>  <!-- result: <div></div> -->
-```
-
-There is another way to format a string attribute: the `t-attf-` directive. With
-it, you get string interpolation:
-
-```xml
-<div t-attf-foo="a {{value1}} is {{value2}} of {{value3}} ]"/>
-<!-- result if values are set to 1,2 and 3: <div foo="a 0 is 1 of 2 ]"></div> -->
-```
-
-For historical reason, there is an alternate form of string interpolation:
-
-```xml
-<div t-attf-foo="a #{value1} is #{value2} of #{value3} ]"/>
-<!-- result if values are set to 1,2 and 3: <div foo="a 0 is 1 of 2 ]"></div> -->
-```
-
-### `t-call` directive (sub templates)
-
-QWeb templates can be used for top level rendering, but they can also be used
-from within another template (to avoid duplication or give names to parts of
-templates), using the `t-call` directive:
-
-```xml
-<div t-name="other-template">
-    <p><t t-value="var"/></p>
-</div>
-
-<div t-name="main-template">
-    <t t-set="var" t-value="owl"/>
-    <t t-call="other-template"/>
-</div>
-```
-
-will be rendered as `<div><p>owl</p></div>`. This example shows that the sub
-template is rendered with the execution context of the parent. The sub template
-is actually inlined in the main template, but in a sub scope: variables defined
-in the sub template do not escape.
-
-Sometimes, one might want to pass information to the sub template. In that case,
-the content of the body of the `t-call` directive is available as a special
-magic variable `0`:
-
-```xml
-<t t-name="other-template">
-    This template was called with content:
-    <t t-raw="0"/>
-</t>
-
-<div t-name="main-template">
-    <t t-call="other-template">
-        <em>content</em>
-    </t>
-</div>
-```
-
-will result in :
-
-```xml
-<div>
-    This template was called with content:
-    <em>content</em>
-</div>
-```
-
-## JS/OWL Specific Extensions
-
-### `t-on` directive
-
-In a component's template, it is useful to be able to register handlers on some
-elements to some specific events. This
-is what makes a template _alive_. There are two different use cases.
-
-1. Register an event handler on a DOM node
-
-   ```xml
-   <button t-on-click="someMethod">Do something</button>
-   ```
-
-   This will be roughly translated in javascript like this:
-
-   ```js
-   button.addEventListener("click", widget.someMethod.bind(widget));
-   ```
-
-   The suffix (`click` in this example) is simply the name of the actual DOM
-   event.
-
-2. Register an event handler on a component. This will not capture a DOM event,
-   but rather a _business_ event:
-
-   ```xml
-   <t t-widget="MyWidget" t-on-menuLoaded="someMethod"/>
-   ```
-
-   ```js
-   class MyWidget {
-       someWhere() {
-           const payload = ...;
-           this.trigger('menuLoaded', payload);
-       }
-   }
-   ```
-
-   Here, the parent widget will receive the payload in its `someMethod` handler,
-   whenever the event is triggered.
-
-The `t-on` directive also allows to prebind some arguments. For example,
-
-```xml
-<button t-on-click="someMethod(expr)">Do something</button>
-```
-
-Here, `expr` is a valid Owl expression, so it could be `true` or some variable
-from the rendering context.
-
-### Component: `t-widget`, `t-props`
-
-The `t-widget` and the `t-props` directives are the key to a declarative component
-system. They allow a template to define where and how a sub widget is created
-and/or updated. For example:
-
-```xml
-<div t-name="ParentWidget">
-    <t t-widget="ChildWidget" t-props="{count: state.val}"/>
-</div>
-```
-
-```js
-class ParentWidget {
-  widgets = { ChildWidget };
-  state = { val: 4 };
-}
-```
-
-Whenever the template is rendered, it will automatically create the subwidget
-`ChildWidget` at the correct place. It needs to find the reference to the
-actual component class in the special `widgets` key.
-
-In this example, the child widget will receive the object `{count: 4}` in its
-constructor. This will be assigned to the `props` variable, which can be accessed
-on the widget (and also, in the template). Whenever the state is updated, then
-the subwidget will also be updated automatically.
-
-### `t-ref` directive
-
-The `t-ref` directive helps a component keep reference to some inside part of it.
-Like the `t-on` directive, it can work either on a DOM node, or on a component:
-
-```xml
-<div>
-    <div t-ref="someDiv"/>
-    <t t-widget="SubWidget" t-ref="someWidget"/>
-</div>
-```
-
-In this example, the widget will be able to access the `div` and the component
-inside the special `refs` variable:
-
-```js
-this.refs.someDiv;
-this.refs.someWidget;
-```
-
-This is useful for various usecases: for example, integrating with an external
-library that needs to render itself inside an actual DOM node. Or for calling
-some method on a sub widget.
-
-Note: if used on a component, the reference will be set in the `refs`
-variable between `willPatch` and `patched`.
-
-### `t-key` directive
-
-Even though Owl tries to be as declarative as possible, some DOM state is still
-locked inside the DOM: for example, the scrolling state, the current user selection,
-the focused element or the state of an input. This is why we use a virtual dom
-algorithm to keep the actual DOM node as much as possible. However, this is
-sometimes not enough, and we need to help Owl decide if an element is actually
-the same, or is different. The `t-key` directive is used to give an identity to an element.
-
-There are three main use cases:
-
-- _elements in a list_:
-
-  ```xml
-    <span t-foreach="todos" t-as="todo" t-key="todo.id">
-        <t t-esc="todo.text"/>
-    </span>
-  ```
-
-- _`t-if`/`t-else`_
-
-- _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 0.5s;
-}
-.fade-enter,
-.fade-leave-to {
-  opacity: 0;
-}
-```
-
-Note: more information on animations are available [here](doc/animations.md).
-
-### `t-mounted` directive
-
-The `t-mounted` directive allows to register a callback to execute whenever the node
-is inserted into the DOM.
-
-```xml
-<div><input t-ref="someInput" t-mounted="focusMe"/></div>
-```
-
-```js
-class MyWidget extends owl.Component {
-    ...
-    focusMe() {
-        this.refs.someInput.focus();
-    }
-}
-```
-
-### Debugging (`t-debug` and `t-log`)
-
-The javascript QWeb implementation provides two useful debugging directives:
-
-`t-debug` adds a debugger statement during template rendering:
-
-```xml
-<t t-if="a_test">
-    <t t-debug="">
-</t>
-```
-
-will stop execution if the browser dev tools are open.
-
-`t-log` takes an expression parameter, evaluates the expression during rendering and logs its result with console.log:
-
-```xml
-<t t-set="foo" t-value="42"/>
-<t t-log="foo"/>
-```
-
-will print 42 to the console
-
-### White spaces
-
-White spaces in a templates are handled in a special way:
-
-- consecutive whitespaces are always condensed to a single whitespace
-- if a whitespace-only text node contains a linebreak, it is ignored
-- the previous rules do not apply if we are in a `<pre>` tag
-
-### Root nodes
-
-For many reasons, Owl QWeb templates should have a single root node. More
-precisely, the result of a template rendering should have a single root node:
-
-```xml
-<!–– not ok: two root nodes ––>
-<t>
-    <div>foo</div>
-    <div>bar</div>
-</t>
-
-<!–– ok: result has one single root node ––>
-<t>
-    <div t-if="someCondition">foo</div>
-    <span t-else="1">bar</span>
-</t>
-```
-
-Extra root nodes will actually be ignored (even though they will be rendered
-in memory).
-
-Note: this does not apply to subtemplates (see the `t-call` directive). In that
-case, they will be inlined in the main template, and can actually have many
-root nodes.

doc/readme.md

@@ -1,16 +1,55 @@
 # 🦉 OWL Documentation 🦉
 
+## Learning Owl
+
+Are you new to Owl? This is the place to start!
+
+- [Tutorial: create a TodoList application](learning/tutorial_todoapp.md)
+- [Quick Overview](learning/overview.md)
+- [How to start an Owl project](learning/quick_start.md)
+- [How to test Components](learning/how_to_test.md)
+- [How to write Single File Components](learning/how_to_write_sfc.md)
+- [How to write debug Owl applications](learning/how_to_debug.md)
 
 ## Reference
 
-- [Component](component.md)
-- [QWeb](qweb.md)
-- [Store](store.md)
-- [Observer](observer.md)
-- [Virtual DOM](vdom.md)
-- [Utils](utils.md)
+You will find here a complete reference of every feature, class or object
+provided by Owl.
 
-## Miscellaneous
-- [Quick Start](quick_start.md)
-- [Animations](animations.md)
-- [Comparison with React/Vue](comparison.md)
+- [Animations](reference/animations.md)
+- [Component](reference/component.md)
+- [Content](reference/content.md)
+- [Concurrency Model](reference/concurrency_model.md)
+- [Configuration](reference/config.md)
+- [Context](reference/context.md)
+- [Environment](reference/environment.md)
+- [Event Bus](reference/event_bus.md)
+- [Event Handling](reference/event_handling.md)
+- [Error Handling](reference/error_handling.md)
+- [Hooks](reference/hooks.md)
+- [Miscellaneous Components](reference/misc.md)
+- [Observer](reference/observer.md)
+- [Props](reference/props.md)
+- [Props Validation](reference/props_validation.md)
+- [QWeb Templating Language](reference/qweb_templating_language.md)
+- [QWeb Engine](reference/qweb_engine.md)
+- [Router](reference/router.md)
+- [Store](reference/store.md)
+- [Slots](reference/slots.md)
+- [Tags](reference/tags.md)
+- [Utils](reference/utils.md)
+
+## Other Topics
+
+This section provides miscellaneous document that explains some topics
+which cannot be considered either a tutorial, or reference documentation.
+
+- [Owl architecture: the Virtual DOM](miscellaneous/vdom.md)
+- [Owl architecture: the rendering pipeline](miscellaneous/rendering.md)
+- [Comparison with React/Vue](miscellaneous/comparison.md)
+- [Why did Odoo built Owl?](miscellaneous/why_owl.md)
+
+---
+
+Found an issue in the documentation? A broken link? Some outdated information?
+Please open an issue or submit a PR!

doc/reference/animations.md

@@ -0,0 +1,95 @@
+# 🦉 Animations 🦉
+
+Animation is a complex topic. There are many different use cases, and many
+solutions and technologies. Owl only supports some basic use cases.
+
+## 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
+<a class="btn flash" t-on-click="doSomething">Click</a>
+```
+
+with the following CSS:
+
+```css
+btn {
+  background-color: gray;
+}
+
+.flash {
+  transition: background 0.5s;
+}
+
+.flash:active {
+  background-color: #41454a;
+  transition: background 0s;
+}
+```
+
+will produce a nice flash effect whenever the user clicks (or activates with the
+keyboard) the button.
+
+## CSS Transitions
+
+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. It works on html elements and
+on components, by adding and removing some css classes.
+
+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
+sequence of events will happen:
+
+At node insertion:
+
+- the css classes `name-enter` and `name-enter-active` will be added directly
+  when the node is inserted into 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 0.5s;
+}
+.fade-enter,
+.fade-leave-to {
+  opacity: 0;
+}
+```
+
+The `t-transition` directive can be applied on a node element or on a component.
+
+Notes:
+
+Owl does not support more than one transition on a single node, so the
+`t-transition` expression must be a single value (i.e. no space allowed).

doc/reference/component.md

@@ -0,0 +1,820 @@
+# 🦉 OWL Component 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Example](#example)
+- [Reference](#reference)
+  - [Reactive System](#reactive-system)
+  - [Properties](#properties)
+  - [Static Properties](#static-properties)
+  - [Methods](#methods)
+  - [Lifecycle](#lifecycle)
+  - [Root Component](#root-component)
+  - [Composition](#composition)
+  - [Form Input Bindings](#form-input-bindings)
+  - [References](#references)
+  - [Dynamic sub components](#dynamic-sub-components)
+  - [Functional Components](#functional-components)
+  - [SVG components](#svg-components)
+
+## Overview
+
+OWL components are the building blocks for user interface. They are designed to be:
+
+1. **declarative:** the user interface should be described in terms of the state
+   of the application, not as a sequence of imperative steps.
+
+2. **composable:** each component can seamlessly be created in a parent component by
+   a simple tag or directive in its template.
+
+3. **asynchronous rendering:** the framework will transparently wait for each
+   sub components to be ready before applying the rendering. It uses native promises
+   under the hood.
+
+4. **uses QWeb as a template system:** the templates are described in XML
+   and follow the QWeb specification. This is a requirement for Odoo.
+
+OWL components are defined as a subclass of Component. The rendering is
+exclusively done by a [QWeb](qweb_templating_language.md) template (which needs to be preloaded in QWeb).
+Rendering a component generates a virtual dom representation
+of the component, which is then patched to the DOM, in order to apply the changes in an efficient way.
+
+## Example
+
+Let us have a look at a simple component:
+
+```javascript
+const { useState } = owl.hooks;
+
+class ClickCounter extends owl.Component {
+  state = useState({ value: 0 });
+
+  increment() {
+    this.state.value++;
+  }
+}
+```
+
+```xml
+<button t-name="ClickCounter" t-on-click="increment">
+  Click Me! [<t t-esc="state.value"/>]
+</button>
+```
+
+Note that this code is written in ESNext style, so it will only run on the
+latest browsers without a transpilation step.
+
+This example shows how a component should be defined: it simply subclasses the
+Component class. If no static `template` key is defined, then
+Owl will use the component's name as template name. Here,
+a state object is defined, by using the `useState` hook. It is not mandatory to use the state object, but it is certainly encouraged. The result of the `useState` call is
+[observed](observer.md), and any change to it will cause a rerendering.
+
+## Reference
+
+An Owl component is a small class which represents a component or some UI element.
+It exists in the context of an [environment](environment.md) (`env`), which is propagated from a
+parent to its children. The environment needs to have a [QWeb](qweb_templating_language.md) instance, which
+will be used to render the component template.
+
+Be aware that the name of the component may be significant: if a component does
+not define a `template` key, then Owl will lookup in QWeb to
+find a template with the component name (or one of its ancestors).
+
+### Reactive system
+
+OWL components are normal javascript classes. So, changing a component internal
+state does nothing more:
+
+```js
+class Counter extends Component {
+  static template = xml`<div t-on-click="increment"><t t-esc="state.value"/></div>`;
+  state = { value: 0 };
+
+  increment() {
+    this.state.value++;
+  }
+}
+```
+
+Clicking on the `Counter` component defined above will call the `increment`
+method, but it will not rerender the component. To fix that, one could add an
+explicit call to `render` in `increment`:
+
+```js
+    increment() {
+        this.state.value++;
+        this.render();
+    }
+```
+
+However, it may be simple in this case, but it quickly become cumbersome, as a
+component get more complex, and its internal state is modified by more than one
+method.
+
+A better way is to use the reactive system: by using the `useState` hook (see the
+[hooks](hooks.md) section for more details), one can make Owl react to state
+changes. The `useState` hook generates a proxy version of an object
+(this is done by an [observer](observer.md)), which allows the component to
+react to any change. So, the `Counter` example above can be improved like this:
+
+```js
+const { useState } = owl.hooks;
+
+class Counter extends Component {
+  static template = xml`<div t-on-click="increment"><t t-esc="state.value"/></div>`;
+  state = useState({ value: 0 });
+
+  increment() {
+    this.state.value++;
+  }
+}
+```
+
+Obviously, we can call the `useState` hook more than once:
+
+```js
+const { useState } = owl.hooks;
+
+class Counter extends Component {
+  static template = xml`
+      <div>
+        <span t-on-click="increment(counter1)"><t t-esc="counter1.value"/></span>
+        <span t-on-click="increment(counter2)"><t t-esc="counter2.value"/></span>
+      </div>`;
+  counter1 = useState({ value: 0 });
+  counter2 = useState({ value: 0 });
+
+  increment(counter) {
+    counter.value++;
+  }
+}
+```
+
+Note that hooks are subject to one important [rule](hooks.md#one-rule): they need
+to be called in the constructor.
+
+### Properties
+
+- **`el`** (HTMLElement | null): reference to the DOM root node of the element. It is `null` when the
+  component is not mounted.
+
+- **`env`** (Object): the component [environment](environment.md), which contains a QWeb instance.
+
+- **`props`** (Object): this is an object containing all the properties given by
+  the parent to a child component. For example, in the following situation,
+  the parent component gives a `user` and a `color` value to the `ChildComponent`.
+
+  ```xml
+    <div>
+      <ChildComponent user="state.user" color="color">
+    </div>
+  ```
+
+  Note that `props` are owned by the parent, not by the component.
+  As such, it should not ever be modified by the component (otherwise you risk
+  unintended effects, since the parent may not be aware of the change)!!
+
+  The `props` can be modified dynamically by the parent. In that case, the
+  component will go through the following lifecycle methods: `willUpdateProps`,
+  `willPatch` and `patched`.
+
+### Static Properties
+
+- **`template`** (string, optional): if given, this is the name of the QWeb template that will render the component. Note that there is a helper `xml` to
+  make it easy to define an inline template.
+
+* **`components`** (Object, optional): if given, this is an object that contains
+  the classes of any sub components needed by the template. This is the main way
+  used by Owl to be able to create sub components.
+
+  ```js
+  class ParentComponent extends owl.Component {
+    static components = { SubComponent };
+  }
+  ```
+
+* **`props`** (Object, optional): if given, this is an object that describes the
+  type and shape of the (actual) props given to the component. If Owl mode is
+  `dev`, this will be used to validate the props each time the component is
+  created/updated. See [Props Validation](props_validation.md) for more information.
+
+  ```js
+  class Counter extends owl.Component {
+    static props = {
+      initialValue: Number,
+      optional: true,
+    };
+  }
+  ```
+
+- **`defaultProps`** (Object, optional): if given, this object define default
+  values for (top-level) props. Whenever `props` are given to the object, they
+  will be altered to add default value (if missing). Note that it does not
+  change the initial object, a new object will be created instead.
+
+  ```js
+  class Counter extends owl.Component {
+    static defaultProps = {
+      initialValue: 0,
+    };
+  }
+  ```
+
+- **`style`** (string, optional): it should be the return value of the [`css` tag](tags.md#css-tag),
+  which is used to inject stylesheet whenever the component is visible on the
+  screen.
+
+There is another static property defined on the `Component` class: `current`.
+This property is set to the currently being defined component (in the constructor).
+This is the way [hooks](hooks.md) are able to get a reference to the target
+component.
+
+### Methods
+
+We explain here all the public methods of the `Component` class.
+
+- **`mount(target, options)`** (async): this is the main way a
+  component is added to the DOM: the root component is mounted to a target
+  HTMLElement (or document fragment). Obviously, this is asynchronous, since each children need to be
+  created as well. Most applications will need to call `mount` exactly once, on
+  the root component.
+
+  The `options` argument is an optional object with a `position` key. The
+  `position` key can have three possible values: `first-child`, `last-child`, `self`.
+
+  - `first-child`: with this option, the component will be prepended inside the target,
+  - `last-child` (default value): with this option, the component will be
+    appended in the target element,
+  - `self`: the target will be used as the root element for the component. This
+    means that the target has to be an HTMLElement (and not a document fragment).
+    In this situation, it is possible that the component cannot be unmounted. For
+    example, if its target is `document.body`.
+
+  Note that if a component is mounted, unmounted and remounted, it will be
+  automatically re-rendered to ensure that changes in its state (or something
+  in the environment, or in the store, or ...) will be taken into account.
+
+  If a component is mounted inside an element or a fragment which is not in the
+  DOM, then it will be rendered fully, but not active: the `mounted` hooks will
+  not be called. This is sometimes useful if we want to load an application in
+  memory. In that case, we need to mount the root component again in an element
+  which is in the DOM:
+
+  ```js
+  const app = new App();
+  await app.mount(document.createDocumentFragment());
+  // app is rendered in memory, but not active
+  await app.mount(document.body);
+  // app is now visible
+  ```
+
+* **`unmount()`**: in case a component needs to be detached/removed from the DOM, this
+  method can be used. Most applications should not call `unmount`, this is more
+  useful to the underlying component system.
+
+* **`render()`** (async): calling this method directly will cause a rerender. Note
+  that this should be very rare to have to do it manually, the Owl framework is
+  most of the time responsible for doing that at an appropriate moment.
+
+  Note that the render method is asynchronous, so one cannot observe the updated
+  DOM in the same stack frame.
+
+* **`shouldUpdate(nextProps)`**: this method is called each time a component's props
+  are updated. It returns a boolean, which indicates if the component should
+  ignore a props update. If it returns false, then `willUpdateProps` will not
+  be called, and no rendering will occur. Its default implementation is to
+  always return true. This is an optimization, similar to React's `shouldComponentUpdate`. Most of the time, this should not be used, but it
+  can be useful if we are handling large number of components.
+
+* **`destroy()`**. As its name suggests, this method will remove the component,
+  and perform all necessary cleanup, such as unmounting the component, its children,
+  removing the parent/children relationship. This method should almost never be
+  called directly (except maybe on the root component), but should be done by the
+  framework instead.
+
+Obviously, these methods are reserved for Owl, and should not be used by Owl
+users, unless they want to override them. Also, Owl reserves all method names
+starting with `__`, in order to prevent possible future conflicts with user code
+whenever Owl needs to change.
+
+### Lifecycle
+
+A solid and robust component system needs useful hooks/methods to help
+developers write components. Here is a complete description of the lifecycle of
+a owl component:
+
+| Method                                           | Description                                                 |
+| ------------------------------------------------ | ----------------------------------------------------------- |
+| **[constructor](#constructorparent-props)**      | constructor                                                 |
+| **[willStart](#willstart)**                      | async, before first rendering                               |
+| **[mounted](#mounted)**                          | just after component is rendered and added to the DOM       |
+| **[willUpdateProps](#willupdatepropsnextprops)** | async, before props update                                  |
+| **[willPatch](#willpatch)**                      | just before the DOM is patched                              |
+| **[patched](#patchedsnapshot)**                  | just after the DOM is patched                               |
+| **[willUnmount](#willunmount)**                  | just before removing component from DOM                     |
+| **[catchError](#catcherrorerror)**               | catch errors (see [error handling page](error_handling.md)) |
+
+Notes:
+
+- hooks call order is precisely defined: `[willX]` hooks are called first on parent,
+  then on children, and `[Xed]` are called in the reverse order: first children,
+  then parent.
+- no hook method should ever be called manually. They are supposed to be
+  called by the owl framework whenever it is required.
+
+#### `constructor(parent, props)`
+
+The constructor is not exactly a hook, it is the regular,
+normal, constructor of the component. Since it is not a hook, you need to make
+sure that `super` is called.
+
+This is usually where you would set the initial state and the template of the
+component.
+
+```javascript
+  constructor(parent, props) {
+    super(parent, props);
+    this.state = useState({someValue: true});
+    this.template = 'mytemplate';
+  }
+```
+
+Note that with ESNext class fields, the constructor method does not need to be
+implemented in most cases:
+
+```javascript
+class ClickCounter extends owl.Component {
+  state = useState({ value: 0 });
+
+  ...
+}
+```
+
+#### `willStart()`
+
+willStart is an asynchronous hook that can be implemented to
+perform some action before the initial rendering of a component.
+
+It will be called exactly once before the initial rendering. It is useful
+in some cases, for example, to load external assets (such as a JS library)
+before the component is rendered. Another use case is to load data from a server.
+
+```javascript
+  async willStart() {
+    await owl.utils.loadJS("my-awesome-lib.js");
+  }
+```
+
+At this point, the component is not yet rendered. Note that a slow `willStart` method will slow down the rendering of the user
+interface. Therefore, some care should be made to make this method as
+fast as possible.
+
+#### `mounted()`
+
+`mounted` is called each time a component is attached to the
+DOM, after the initial rendering and possibly later if the component was unmounted
+and remounted. At this point, the component is considered _active_. This is a good place to add some listeners, or to interact with the
+DOM, if the component needs to perform some measure for example.
+
+It is the opposite of `willUnmount`. If a component has been mounted, it will
+always be unmounted at some point in the future.
+
+The mounted method will be called recursively on each of its children. First,
+the parent, then all its children.
+
+It is allowed (but not encouraged) to modify the state in the `mounted` hook.
+Doing so will cause a rerender, which will not be perceptible by the user, but
+will slightly slow down the component.
+
+#### `willUpdateProps(nextProps)`
+
+The willUpdateProps is an asynchronous hook, called just before new props
+are set. This is useful if the component needs to perform an asynchronous task,
+depending on the props (for example, assuming that the props are
+some record Id, fetching the record data).
+
+```javascript
+  willUpdateProps(nextProps) {
+    return this.loadData({id: nextProps.id});
+  }
+```
+
+This hook is not called during the first render (but willStart is called
+and performs a similar job).
+
+#### `willPatch()`
+
+The willPatch hook is called just before the DOM patching process starts.
+It is not called on the initial render. This is useful to read
+information from the DOM. For example, the current position of the
+scrollbar.
+
+Note that modifying the state is not allowed here. This method is called just
+before an actual DOM patch, and is only intended to be used to save some local
+DOM state. Also, it will not be called if the component is not in the DOM.
+
+#### `patched(snapshot)`
+
+This hook is called whenever a component did actually update its DOM (most
+likely via a change in its state/props or environment).
+
+This method is not called on the initial render. It is useful to interact
+with the DOM (for example, through an external library) whenever the
+component was patched. Note that this hook will not be called if the component is
+not in the DOM.
+
+Updating the component state in this hook is possible, but not encouraged.
+One needs to be careful, because updates here will create an additional rendering, which in
+turn will cause other calls to the `patched` method. So, we need to be particularly
+careful at avoiding endless cycles.
+
+#### `willUnmount()`
+
+willUnmount is a hook that is called each time just before a component is unmounted from
+the DOM. This is a good place to remove listeners, for example.
+
+```javascript
+  mounted() {
+    this.env.bus.on('someevent', this, this.doSomething);
+  }
+  willUnmount() {
+    this.env.bus.off('someevent', this, this.doSomething);
+  }
+```
+
+This is the opposite method of `mounted`.
+
+#### `catchError(error)`
+
+The `catchError` method is useful when we need to intercept and properly react
+to (rendering) errors that occur in some sub components. See the page on
+[error handling](error_handling.md).
+
+### Root Component
+
+Most of the time, an Owl component will be created automatically by a tag (or the `t-component`
+directive) in a template. There is however an obvious exception: the root component
+of an Owl application has to be created manually:
+
+```js
+class App extends owl.Component { ... }
+
+const app = new App();
+app.mount(document.body);
+```
+
+The root component does not have a parent nor `props` (see note below). It will be setup with an
+[environment](environment.md) (either the `env` defined on its class, or a
+default empty environment).
+
+Note: a root component can however be given a `props` object in its constructor,
+like this: `new App(null, {some: 'object'});`. It will not be a true `props`
+object, managed by Owl (so, for example, it will never be updated).
+
+### Composition
+
+The example above shows a QWeb template with a sub component. In a template,
+components are declared with a tagname corresponding to the class name. It has
+to be capitalized.
+
+```xml
+<div t-name="ParentComponent">
+  <span>some text</span>
+  <MyComponent info="13" />
+</div>
+```
+
+```js
+class ParentComponent extends owl.Component {
+    static components = { MyComponent: MyComponent};
+    ...
+}
+```
+
+In this example, the `ParentComponent`'s template creates a component `MyComponent` just
+after the span. The `info` key will be added to the subcomponent's `props`. Each
+`props` is a string which represents a javascript (QWeb) expression, so it is
+dynamic. If it is necessary to give a string, this can be done by quoting it:
+`someString="'somevalue'"`.
+
+Note that the rendering context for the template is the component itself. This means
+that the template can access `state` (if it exists), `props`, `env`, or any
+methods defined in the component.
+
+```xml
+<div t-name="ParentComponent">
+    <ChildComponent count="state.val" />
+</div>
+```
+
+```js
+class ParentComponent {
+  static components = { ChildComponent };
+  state = useState({ val: 4 });
+}
+```
+
+Whenever the template is rendered, it will automatically create the subcomponent
+`ChildComponent` at the correct place. It needs to find the reference to the
+actual component class in the special static `components` key, or the class registered in
+QWeb's global registry (see `register` function of QWeb). It first looks inside
+the static `components` key, then fallbacks on the global registry.
+
+_Props_: In this example, the child component will receive the object `{count: 4}` in its
+constructor. This will be assigned to the `props` variable, which can be accessed
+on the component (and also, in the template). Whenever the state is updated, then
+the sub component will also be updated automatically. See the [props section](props.md)
+for more information.
+
+**CSS and style:** Owl allows the parent to declare
+additional css classes or style for the sub component: css declared in `class`, `style`, `t-att-class` or `t-att-style` will be added to the
+root component element.
+
+```xml
+<div t-name="ParentComponent">
+  <MyComponent class="someClass" style="font-weight:bold;" info="13" />
+</div>
+```
+
+Warning: there is a small caveat with dynamic class attributes: since Owl needs
+to be able to add/remove proper classes whenever necessary, it needs to be aware
+of the possible classes. Otherwise, it will not be able to make the difference
+between a valid css class added by the component, or other custom code, and a
+class that need to be removed. This is why we only support the explicit syntax
+with a class object:
+
+```xml
+<MyComponent t-att-class="{a: state.flagA, b: state.flagB}" />
+```
+
+### Form Input Bindings
+
+It is very common to need to be able to read the value out of an html `input` (or
+`textarea`, or `select`) in order to use it (note: it does not need to be in a
+form!). A possible way to do this is to do it by hand:
+
+```js
+class Form extends owl.Component {
+  state = useState({ text: "" });
+
+  _updateInputValue(event) {
+    this.state.text = event.target.value;
+  }
+}
+```
+
+```xml
+<div>
+  <input t-on-input="_updateInputValue" />
+  <span t-esc="state.text" />
+</div>
+```
+
+This works. However, this requires a little bit of _plumbing_ code. Also, the
+plumbing code is slightly different if you need to interact with a checkbox,
+or with radio buttons, or with select tags.
+
+To help with this situation, Owl has a builtin directive `t-model`: its value
+should be an observed value in the component (usually `state.someValue`). With
+the `t-model` directive, we can write a shorter code, equivalent to the previous
+example:
+
+```js
+class Form extends owl.Component {
+  state = { text: "" };
+}
+```
+
+```xml
+<div>
+  <input t-model="state.text" />
+  <span t-esc="state.text" />
+</div>
+```
+
+The `t-model` directive works with `<input>`, `<input type="checkbox">`,
+`<input type="radio">`, `<textarea>` and `<select>`:
+
+```xml
+<div>
+    <div>Text in an input: <input t-model="state.someVal"/></div>
+    <div>Textarea: <textarea t-model="state.otherVal"/></div>
+    <div>Boolean value: <input type="checkbox" t-model="state.someFlag"/></div>
+    <div>Selection:
+        <select t-model="state.color">
+            <option value="">Select a color</option>
+            <option value="red">Red</option>
+            <option value="blue">Blue</option>
+        </select>
+    </div>
+    <div>
+        Selection with radio buttons:
+        <span>
+            <input type="radio" name="color" id="red" value="red" t-model="state.color"/>
+            <label for="red">Red</label>
+        </span>
+        <span>
+            <input type="radio" name="color" id="blue" value="blue" t-model="state.color" />
+            <label for="blue">Blue</label>
+        </span>
+    </div>
+</div>
+```
+
+Like event handling, the `t-model` directive accepts the following modifiers:
+
+| Modifier  | Description                                                          |
+| --------- | -------------------------------------------------------------------- |
+| `.lazy`   | update the value on the `change` event (default is on `input` event) |
+| `.number` | try to parse the value to a number (using `parseFloat`)              |
+| `.trim`   | trim the resulting value                                             |
+
+For example:
+
+```xml
+<input t-model.lazy="state.someVal" />
+```
+
+These modifiers can be combined. For instance, `t-model.lazy.number` will only
+update a number whenever the change is done.
+
+Note: the online playground has an example to show how it works.
+
+### References
+
+The `useRef` hook is useful when we need a way to interact with some inside part
+of a component, rendered by Owl. It can work either on a DOM node, or on a component,
+tagged by the `t-ref` directive. See the [hooks section](hooks.md#useref) for
+more detail.
+
+As a short example, here is how we could set the focus on a given input:
+
+```xml
+<div>
+    <input t-ref="input"/>
+    <button t-on-click="focusInput">Click</button>
+</div>
+```
+
+```js
+import { useRef } from "owl/hooks";
+
+class SomeComponent extends Component {
+  inputRef = useRef("input");
+
+  focusInput() {
+    this.inputRef.el.focus();
+  }
+}
+```
+
+The `useRef` hook can also be used to get a reference to an instance of a sub
+component rendered by Owl. In that case, we need to access it with the `comp`
+property instead of `el`:
+
+```xml
+<div>
+    <SubComponent t-ref="sub"/>
+    <button t-on-click="doSomething">Click</button>
+</div>
+```
+
+```js
+import { useRef } from "owl/hooks";
+
+class SomeComponent extends Component {
+  static components = { SubComponent };
+  subRef = useRef("sub");
+
+  doSomething() {
+    this.subRef.comp.doSomeThingElse();
+  }
+}
+```
+
+Note that these two examples uses the suffix `ref` to name the reference. This
+is not mandatory, but it is a useful convention, so we do not forget to access
+it with the `el` or `comp` suffix.
+
+### Dynamic sub components
+
+It is not common, but sometimes we need a dynamic component name. In this case,
+the `t-component` directive can also be used to accept dynamic values with string interpolation (like the [`t-attf-`](qweb_templating_language.md#dynamic-attributes) directive):
+
+```xml
+<div t-name="ParentComponent">
+    <t t-component="ChildComponent{{id}}" />
+</div>
+```
+
+```js
+class ParentComponent {
+  static components = { ChildComponent1, ChildComponent2 };
+  state = { id: 1 };
+}
+```
+
+There is an even more dynamic way to use `t-component`: its value can be an
+expression evaluating to an actual component class. In that case, this is the
+class that will be used to create the component:
+
+```js
+class A extends Component<any, any, any> {
+  static template = xml`<span>child a</span>`;
+}
+class B extends Component<any, any, any> {
+  static template = xml`<span>child b</span>`;
+}
+class App extends Component<any, any, any> {
+  static template = xml`<t t-component="myComponent" t-key="state.child"/>`;
+
+  state = { child: "a" };
+
+  get myComponent() {
+    return this.state.child === "a" ? A : B;
+  }
+}
+```
+
+In this example, the component `App` selects dynamically the concrete sub
+component class.
+
+Note that the `t-component` directive can only be used on `<t>` nodes.
+
+### Functional Components
+
+Owl does not exactly have functional components. However, there is an extremely
+close alternative: calling sub templates.
+
+A stateless functional component in react is usually some kind of function that
+maps props to a virtual dom (often with `jsx`). So, basically, almost like a
+template rendered with `props`. In Owl, this can be done by
+simply defining a template, that will access the `props` object:
+
+```js
+const Welcome = xml`<h1>Hello, {props.name}</h1>`;
+
+class MyComponent extends Component {
+  static template = xml`
+        <div>
+            <t t-call=${Welcome}/>
+            <div>something</div>
+        </div>
+    `;
+}
+```
+
+The way this works is that sub templates are inlined, and have access to the
+ambient context. They can therefore access `props`, and any other part of the
+caller component.
+
+### SVG Components
+
+Owl components can be used to generate dynamic SVG graphs:
+
+```js
+class Node extends Component {
+  static template = xml`
+        <g>
+            <circle t-att-cx="props.x" t-att-cy="props.y" r="4" fill="black"/>
+            <text t-att-x="props.x - 5" t-att-y="props.y + 18"><t t-esc="props.node.label"/></text>
+            <t t-set="childx" t-value="props.x + 100"/>
+            <t t-set="height" t-value="props.height/(props.node.children || []).length"/>
+            <t t-foreach="props.node.children || []" t-as="child">
+                <t t-set="childy" t-value="props.y + child_index*height"/>
+                <line t-att-x1="props.x" t-att-y1="props.y" t-att-x2="childx" t-att-y2="childy" stroke="black" />
+                <Node x="childx" y="childy" node="child" height="height"/>
+            </t>
+        </g>
+    `;
+  static components = { Node };
+}
+
+class RootNode extends Component {
+  static template = xml`
+        <svg height="180">
+            <Node node="graph" x="10" y="20" height="180"/>
+        </svg>
+    `;
+  static components = { Node };
+  graph = {
+    label: "a",
+    children: [
+      { label: "b" },
+      { label: "c", children: [{ label: "d" }, { label: "e" }] },
+      { label: "f", children: [{ label: "g" }] },
+    ],
+  };
+}
+```
+
+This `RootNode` component will then display a live SVG representation of the
+graph described by the `graph` property. Note that there is a recursive structure
+here: the `Node` component uses itself as a subcomponent.
+
+Note that since SVG needs to be handled in a specific way (its namespace needs
+to be properly set), there is a small constraint for Owl components: if an owl
+component is supposed to be a part of an svg graph, then its root node needs to
+be a `g` tag, so Owl can properly set the namespace.

doc/reference/concurrency_model.md

@@ -0,0 +1,183 @@
+# 🦉 Concurrency Model 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Rendering Components](#rendering-components)
+- [Semantics](#semantics)
+- [Asynchronous Rendering](#asynchronous-rendering)
+
+## Overview
+
+Owl was designed from the very beginning with asynchronous components. This comes
+from the `willStart` and the `willUpdateProps` lifecycle hooks. With these
+methods, it is possible to build complex highly concurrent applications.
+
+Owl concurrent mode has several benefits: it makes it possible to delay the
+rendering until some asynchronous operation is complete, it makes it possible
+to lazy load libraries, while keeping the previous screen completely functional.
+It is also good for performance reasons: Owl uses it to only apply the result of
+many different renderings only once in an animation frame. Owl can cancel
+a rendering that is no longer relevant, restart it, reuse it in some cases.
+
+But even though using concurrency is quite simple (and is the default behaviour),
+asynchrony is difficult, because it introduces an additional dimension that
+vastly increase the complexity of an application. This section will explain
+how Owl manages this complexity, how concurrent rendering works in a general way.
+
+## Rendering Components
+
+The word _rendering_ is a little vague, so, let us explain more precisely the
+process by which Owl components are displayed on a screen.
+
+When a component is mounted or updated, a new rendering is started. It has
+two phases: _virtual rendering_ and _patching_.
+
+### Virtual rendering
+
+This phase represent the process of rendering a template, in memory, which create a virtual representation of the desired component html). The output of this phase is a
+virtual DOM.
+
+It is asynchronous: each subcomponents needs to either be created (so, `willStart`
+will need to be called), or updated (which is done with the `willUpdateProps`
+method). This is completely a recursive process: a component is the root of a
+component tree, and each sub component needs to be (virtually) rendered.
+
+### Patching
+
+Once a rendering is complete, it will be applied on the next animation frame.
+This is done synchronously: the whole component tree is patched to the real
+DOM.
+
+## Semantics
+
+We give here an informal description of the way components are created/updated
+in an application. Here, ordered lists describe actions that are executed
+sequentially, bullet lists describe actions that are executed in parallel.
+
+**Scenario 1: initial rendering** Imagine we want to render the following component tree:
+
+```
+        A
+       / \
+      B   C
+         / \
+        D   E
+```
+
+Here is what happen whenever we mount the root
+component (with some code like `app.mount(document.body)`).
+
+1. `willStart` is called on `A`
+
+2. when it is done, template `A` is rendered.
+
+   - component `B` is created
+     1. `willStart` is called on `B`
+     2. template `B` is rendered
+   - component `C` is created
+     1. `willStart` is called on `C`
+     2. template `C` is rendered
+        - component `D` is created
+          1. `willStart` is called on `D`
+          2. template `D` is rendered
+        - component `E` is created
+          1. `willStart` is called on `E`
+          2. template `E` is rendered
+
+3. each components are patched into a detached DOM element, in the following order:
+   `E`, `D`, `C`, `B`, `A`. (so the actual full DOM tree is created
+   in one pass)
+
+4. the component `A` root element is actually appended to `document.body`
+
+5. The method `mounted` is called recursively on all components in the following
+   order: `E`, `D`, `C`, `B`, `A`.
+
+**Scenario 2: rerendering a component**. Now, let's assume that the user clicked on some
+button in `C`, and this results in a state update, which is supposed to:
+
+- update `D`,
+- remove `E`,
+- add new component `F`.
+
+So, the component tree should look like this:
+
+```
+        A
+       / \
+      B   C
+         / \
+        D   F
+```
+
+Here is what Owl will do:
+
+1. because of a state change, the method `render` is called on `C`
+2. template `C` is rendered again
+
+   - component `D` is updated:
+     1. hook `willUpdateProps` is called on `D` (async)
+     2. template `D` is rerendered
+   - component `F` is created:
+     1. hook `willStart` is called on `F` (async)
+     2. template `F` is rendered
+
+3. `willPatch` hooks are called recursively on components `C`, `D` (not on `F`,
+   because it is not mounted yet)
+
+4. components `F`, `D` are patched in that order
+
+5. component `C` is patched, which will cause recursively:
+
+   1. `willUnmount` hook on `E`
+   2. destruction of `E`,
+
+6. `mounted` hook is called on `F`, `patched` hooks are called on `D`, `C`
+
+Tags are very small helpers to make it easy to write inline templates. There is
+only one currently available tag: `xml`, but we plan to add other tags later,
+such as a `css` tag, which will be used to write [single file components](../learning/how_to_write_sfc.md).
+
+### Asynchronous Rendering
+
+Working with asynchronous code always adds a lot of complexity to a system. Whenever
+different parts of a system are active at the same time, one needs to think
+carefully about all possible interactions. Clearly, this is also true for Owl
+components.
+
+There are two different common problems with Owl asynchronous rendering model:
+
+- any component can delay the rendering (initial and subsequent) of the whole
+  application
+- for a given component, there are two independant situations that will trigger an
+  asynchronous rerendering: a change in the state, or a change in the props.
+  These changes may be done at different times, and Owl has no way of knowing
+  how to reconcile the resulting renderings.
+
+Here are a few tips on how to work with asynchronous components:
+
+1. Minimize the use of asynchronous components!
+2. Maybe move the asynchronous logic in a store, which then triggers (mostly)
+   synchronous renderings
+3. Lazy loading external libraries is a good use case for async rendering. This
+   is mostly fine, because we can assume that it will only takes a fraction of a
+   second, and only once (see [`owl.utils.loadJS`](utils.md#loadjs))
+4. For all the other cases, the [`AsyncRoot`](misc.md#asyncroot) component is there to help you. When
+   this component is met, a new rendering
+   sub tree is created, such that the rendering of that component (and its
+   children) is not tied to the rendering of the rest of the interface. It can
+   be used on an asynchronous component, to prevent it from delaying the
+   rendering of the whole interface, or on a synchronous one, such that its
+   rendering isn't delayed by other (asynchronous) components. Note that this
+   directive has no effect on the first rendering, but only on subsequent ones
+   (triggered by state or props changes).
+
+   ```xml
+   <div t-name="ParentComponent">
+     <SyncChild />
+     <AsyncRoot>
+        <AsyncChild/>
+     </AsyncRoot>
+   </div>
+   ```

doc/reference/config.md

@@ -0,0 +1,44 @@
+# 🦉 Config 🦉
+
+The Owl framework is designed to work in many situations. However, it is
+sometimes necessary to customize some behaviour. This is done by using the
+global `config` object. It provides two settings:
+
+- [`mode`](#mode) (default value: `prod`),
+- [`enableTransitions`](#enabletransitions) (default value: `true`).
+
+## Mode
+
+By default, Owl is in _production_ mode, this means that it will try to do its
+job fast, and skip some expensive operations. However, it is sometimes necessary
+to have better information on what is going on, this is the purpose
+of the `dev` mode.
+
+Owl has a mode flag, in `owl.config.mode`. Its default value is `prod`, but
+it can be set to `dev`:
+
+```js
+owl.config.mode = "dev";
+```
+
+Note that templates compiled with the `prod` settings will not be recompiled.
+So, changing this setting is best done at startup.
+
+An important job done by the `dev` mode is to validate props for each component
+creation and update. Also, extra props will cause an error.
+
+## `enableTransitions`
+
+Transitions are usually nice, but they can cause issues in some specific cases,
+such as automated tests. It is uncomfortable having to wait for a transition
+to end before moving to the next step.
+
+To solve this issue, Owl can be configured to ignore the `t-transition` directive.
+To do that, one only needs to set the `enableTransitions` flag to false:
+
+```js
+owl.config.enableTransitions = false;
+```
+
+Note that it suffers from the same drawback as the "dev" mode: all compiled
+templates, if any, will keep their current behaviours.

doc/reference/content.md

@@ -0,0 +1,36 @@
+# 🦉 Owl Content 🦉
+
+Here is a complete visual representation of everything exported by the `owl`
+global object.
+
+For example, `Component` is available at `owl.Component` and `EventBus` is
+exported as `owl.core.EventBus`.
+
+```
+Component                               misc
+Context                                     AsyncRoot
+QWeb                                        Portal
+Store                                   router
+useState                                    Link
+config                                      RouteComponent
+    mode                                    Router
+core                                    tags
+    EventBus                                css
+    Observer                                xml
+hooks                                   utils
+    onWillStart                             debounce
+    onMounted                               escape
+    onWillUpdateProps                       loadJS
+    onWillPatch                             loadFile
+    onPatched                               shallowEqual
+    onWillUnmount                           whenReady
+    useContext
+    useState
+    useRef
+    useSubEnv
+    useStore
+    useDispatch
+    useGetters
+```
+
+Note that for convenience, the `useState` hook is also exported at the root of the `owl` object.

doc/reference/context.md

@@ -0,0 +1,105 @@
+# 🦉 Context 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Example](#example)
+- [Reference](#reference)
+  - [`Context`](#context)
+  - [`useContext`](#usecontext)
+
+## Overview
+
+The `Context` object provides a way to share data between an arbitrary number
+of components. Usually, data is passed from a parent to its children component,
+but when we have to deal with some mostly global information, this can be
+annoying, since each component will need to pass the information to each children,
+even though some or most of them will not use the information.
+
+With a `Context` object, each component can subscribe (with the `useContext` hook)
+to its state, and will be updated whenever the context state is updated.
+
+## Example
+
+Assume that we have an application with various components which needs to render
+differently depending on the size of the device. Here is how we could proceed
+to make sure that the information is properly shared. First, let us create a
+context, and add it to the environment:
+
+```js
+const deviceContext = new Context({ isMobile: true });
+App.env.deviceContext = deviceContext;
+```
+
+If we want to make it completely responsive, we need to update its value whenever
+the size of the screen is updated:
+
+```js
+const isMobile = () => window.innerWidth <= 768;
+window.addEventListener(
+  "resize",
+  owl.utils.debounce(() => {
+    const state = deviceContext.state;
+    if (state.isMobile !== isMobile()) {
+      state.isMobile = !state.isMobile;
+    }
+  }, 15)
+);
+```
+
+Then, each component that want can subscribe and render differently depending on the
+fact that we are in a mobile or desktop mode.
+
+```js
+class SomeComponent extends Component {
+  static template = xml`
+    <div>
+      <t t-if=device.isMobile>
+          some simplified user interface
+      </t>
+      <t t-else="">
+          a more advanced user interface
+      </t>
+    </div>`;
+  device = useContext(this.env.deviceContext);
+}
+```
+
+## Reference
+
+### `Context`
+
+A `Context` object should be created with a state object:
+
+```js
+const someContext = new Context({ some: "key" });
+```
+
+Its state is now available in the `state` key:
+
+```js
+someContext.state.some = "other key";
+```
+
+This is the way some global code (such as the responsive code above) should
+read and update the context state. However, components should not ever read the
+context state directly from the context, they should instead use the `useContext`
+hook to properly register themselves to state changes.
+
+Note that the `Context` hook is different from the React version. For example,
+there is no concept of provider/consumer. So, the `Context` feature does not
+by itself allow the use of a different context state depending on the component
+place in the component tree. However, this functionality can be obtained, if
+necessary, with the use of sub environment.
+
+### `useContext`
+
+The `useContext` hook is the normal way for a component to register themselve
+to context state changes. The `useContext` method returns the context state:
+
+```js
+device = useContext(this.env.deviceContext);
+```
+
+It is a simple observed state (with an owl `Observer`), which contains the shared
+information.

doc/reference/environment.md

@@ -0,0 +1,151 @@
+# 🦉 Environment 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Setting an Environment](#setting-an-environment)
+- [Using a sub environment](#using-a-sub-environment)
+- [Content of an Environment](#content-of-an-environment)
+- [Special keys](#special-keys)
+
+## Overview
+
+An environment is an object which contains a [`QWeb` instance](qweb_engine.md). Whenever
+a root component is created, it is assigned an environment (see
+[below](#setting-an-environment) for more info on this). This environment is
+then automatically given to each sub component (and accessible in the `this.env`
+property).
+
+```
+    Root
+    /  \
+   A    B
+```
+
+This way, all components share the same `QWeb` instance. Owl internally requires
+that the environment has a `qweb` key which maps to a
+[`QWeb`](qweb_engine.md) instance. This is the QWeb instance that will be used to
+render each templates in this specific component tree. Note that if no `QWeb`
+instance is provided, Owl will simply generate it on the fly.
+
+The environment is mostly static. Each application is free to add anything to
+the environment, which is very useful, since this can be accessed by each sub
+component.
+
+## Setting an environment
+
+An Owl application needs an [environment](environment.md) to be executed. The
+environment has an important key: the [QWeb](qweb_engine.md) instance, which will render
+all templates.
+
+Whenever a root component `App` is mounted, Owl will setup a valid environment by
+following the next steps:
+
+- take the `env` object defined on `App.env` (if no `env` was explicitly setup,
+  this will return the empty `env` object defined on `Component`)
+- if `env.qweb` is not set, then Owl will create a `QWeb` instance.
+
+The correct way to customize an environment is to simply set it up on the root
+component class, before the first component is created:
+
+```js
+App.env = {
+    _t: myTranslateFunction,
+    user: {...},
+    services: {
+        ...
+    },
+};
+const app = new App();
+app.mount(document.body);
+```
+
+It is also possible to simply share an environment between all root components,
+by simply doing this:
+
+```js
+Component.env = myEnv; // will be the default env for all components
+```
+
+Note that this environment is the global owl environment for an application. The
+next section explains how to extend an environment for a specific sub component
+and its children.
+
+## Using a sub environment
+
+It is sometimes useful to add one (or more) specific keys to the environment,
+from the perspective of a specific component and its children. In that case, the
+solution presented above will not work, since it sets the global environment.
+
+There is a hook for this situation: [`useSubEnv`](hooks.md#usesubenv).
+
+```js
+class FormComponent extends Component {
+  constructor(parent, props) {
+    super(parent, props);
+    useSubEnv({ myKey: someValue });
+  }
+}
+```
+
+## Content of an Environment
+
+Some good use cases for additional keys in the environment are:
+
+- some configuration keys,
+- session information,
+- generic services (such as doing rpcs).
+
+Doing it this way means that components are easily testable: we can simply
+create a test environment with mock services.
+
+For example:
+
+```js
+async function myEnv() {
+  const templates = await loadTemplates();
+  const qweb = new QWeb({ templates });
+  const session = getSession();
+
+  return {
+    _t: myTranslateFunction,
+    session: session,
+    qweb: qweb,
+    services: {
+      localStorage: localStorage,
+      rpc: rpc,
+    },
+    debug: false,
+    inMobileMode: true,
+  };
+}
+
+async function start() {
+  App.env = await myEnv();
+  const app = new App();
+  await app.mount(document.body);
+}
+```
+
+## Special Keys
+
+There are two special key/value added by Owl if not provided in the environment:
+the `QWeb` instance and a `browser` object:
+
+- `qweb` will be set to an empty `QWeb` instance. This is absolutely necessary
+  for Owl to be able to render anything
+- `browser`: this is an object that contains some common access points to the
+  browser methods with a side effect. This is particularly useful when one want
+  to test more advanced components, and be able to mock those methods.
+
+More specifically, the `browser` object contains the following methods and objects:
+
+- `setTimeout`
+- `clearTimeout`
+- `setInterval`
+- `clearInterval`
+- `requestAnimationFrame`
+- `random`
+- `Date`
+- `fetch`
+- `localStorage`

doc/reference/error_handling.md

@@ -0,0 +1,81 @@
+# 🦉 Error Handling 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Example](#example)
+- [Reference](#reference)
+
+## Overview
+
+By default, whenever an error occurs in the rendering of an Owl application, we
+destroy the whole application. Otherwise, we cannot offer any guarantee on the
+state of the resulting component tree. It might be hopelessly corrupted, but
+without any user-visible state.
+
+Clearly, it sometimes is a little bit extreme to destroy the application. This
+is why we have a builtin mechanism to handle rendering errors (and errors coming
+from lifecycle hooks): the `catchError` hook.
+
+## Example
+
+For example, here is how we could implement an `ErrorBoundary` component:
+
+```xml
+<div t-name="ErrorBoundary">
+    <t t-if="state.error">
+        Error handled
+    </t>
+    <t t-else="">
+        <t t-slot="default" />
+    </t>
+</div>
+```
+
+```js
+class ErrorBoundary extends Component {
+  state = useState({ error: false });
+
+  catchError() {
+    this.state.error = true;
+  }
+}
+```
+
+Using the `ErrorBoundary` is then extremely simple:
+
+```xml
+<ErrorBoundary><SomeOtherComponent/></ErrorBoundary>
+```
+
+Note that we need to be careful here: the fallback UI should not throw any
+error, otherwise we risk going into an infinite loop (also, see the page on
+[slots](slots.md) for more information on the `t-slot` directive).
+
+## Reference
+
+Whenever the `catchError` lifecycle hook is implemented, all errors coming from
+sub components rendering and/or lifecycle method calls will be caught and given
+to the `catchError` method. This allows us to properly handle the error, and to
+not break the application.
+
+There are important things to know:
+
+- If an error that occured in the internal rendering cycle is not caught, then
+  Owl will destroy the full application. This is done on purpose, because Owl
+  cannot guarantee that the state is not corrupted from this point on.
+
+- errors coming from event handlers are NOT managed by `catchError` or any other
+  owl mechanism. This is up to the application developer to properly recover
+  from an error
+
+Also, it may be useful to know that whenever an error is caught, it is then
+broadcasted to the application by an event on the `qweb` instance. It may be
+useful, for example, to log the error somewhere.
+
+```js
+env.qweb.on("error", null, function (error) {
+  // do something
+  // react to the error
+});
+```

doc/reference/event_bus.md

@@ -0,0 +1,27 @@
+# 🦉 Event Bus 🦉
+
+It is sometimes useful to use a `Bus` to communicate informations between various
+parts of the code. Owl has a very simple bus class, which manages subscriptions,
+triggering events, and callbacks.
+
+```js
+const bus = new owl.core.EventBus();
+
+bus.on("some-event", null, function (...args) {
+  console.log(...args);
+});
+
+bus.trigger("some-event", 1, 2, 3);
+// [1,2,3] will be logged to the console
+```
+
+Its API is:
+
+| Method                           | Description                       |
+| -------------------------------- | --------------------------------- |
+| `on(eventType, owner, callback)` | add a listener                    |
+| `off(eventType, owner)`          | remove all listeners for an owner |
+| `trigger(eventType, ...args)`    | trigger an event                  |
+| `clear`                          | remove all subscriptions          |
+
+Note that the [`Store`](store.md) is an example of an `EventBus`.

doc/reference/event_handling.md

@@ -0,0 +1,151 @@
+# 🦉 Event Handling 🦉
+
+## Content
+
+- [Event Handling](#event-handling)
+- [Business DOM Events](#business-dom-events)
+- [Inline Event Handlers](#inline-event-handlers)
+- [Modifiers](#modifiers)
+
+## Event Handling
+
+In a component's template, it is useful to be able to register handlers on DOM
+elements to some specific events. This is what makes a template _alive_. There
+are four different use cases.
+
+1. Register an event handler on a DOM node (_pure_ DOM event)
+2. Register an event handler on a component (_pure_ DOM event)
+3. Register an event handler on a DOM node (_business_ DOM event)
+4. Register an event handler on a component (_business_ DOM event)
+
+A _pure_ DOM event is directly triggered by a user interaction (e.g. a `click`).
+
+```xml
+<button t-on-click="someMethod">Do something</button>
+```
+
+This will be roughly translated in javascript like this:
+
+```js
+button.addEventListener("click", component.someMethod.bind(component));
+```
+
+The suffix (`click` in this example) is simply the name of the actual DOM
+event.
+
+## Business DOM Events
+
+A _business_ DOM event is triggered by a call to `trigger` on a component.
+
+```xml
+<MyComponent t-on-menu-loaded="someMethod" />
+```
+
+```js
+ class MyComponent {
+     someWhere() {
+         const payload = ...;
+         this.trigger('menu-loaded', payload);
+     }
+ }
+```
+
+The call to `trigger` generates an `OwlEvent`, a subclass of [_CustomEvent_](https://developer.mozilla.org/docs/Web/Guide/Events/Creating_and_triggering_events)
+with an additional attribute `originalComponent` (the component that triggered
+the event). The generated event is of type `menu-loaded` and dispatches it on
+the component's DOM element (`this.el`). The event bubbles and is cancelable.
+The parent component listening to event `menu-loaded` will receive the payload
+in its `someMethod` handler (in the `detail` property of the event), whenever
+the event is triggered.
+
+```js
+ class ParentComponent {
+     someMethod(ev) {
+         const payload = ev.detail;
+         ...
+     }
+ }
+```
+
+By convention, we use KebabCase for the name of _business_ events.
+
+The `t-on` directive allows to prebind its arguments. For example,
+
+```xml
+<button t-on-click="someMethod(expr)">Do something</button>
+```
+
+Here, `expr` is a valid Owl expression, so it could be `true` or some variable
+from the rendering context.
+
+### Type Hinting
+
+Note that if you work with Typescript, the `trigger` method is generic on the type of the payload.
+
+You can then describe the type of the event, so you will see typing errors...
+
+```typescript
+this.trigger<MyCustomPayload>("my-custom-event", payload);
+```
+
+```typescript
+myCustomEventHandler(ev: OwlEvent<MyCustomPayload>) { ... }
+```
+
+## Inline Event Handlers
+
+One can also directly specify inline statements. For example,
+
+```xml
+<button t-on-click="state.counter++">Increment counter</button>
+```
+
+Here, `state` must be defined in the rendering context (typically the component)
+as it will be translated to:
+
+```js
+button.addEventListener("click", () => {
+  context.state.counter++;
+});
+```
+
+Warning: inline expressions are evaluated in the context of the template. This
+means that they can access the component methods and properties. But if they set
+a key, the inline statement will actually not modify the component, but a key in
+a sub scope.
+
+```xml
+<button t-on-click="value = 1">Set value to 1 (does not work!!!)</button>
+<button t-on-click="state.value = 1">Set state.value to 1 (work as expected)</button>
+```
+
+## Modifiers
+
+In order to remove the DOM event details from the event handlers (like calls to
+`event.preventDefault`) and let them focus on data logic, _modifiers_ can be
+specified as additional suffixes of the `t-on` directive.
+
+| Modifier   | Description                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `.stop`    | calls `event.stopPropagation()` before calling the method                                                                |
+| `.prevent` | calls `event.preventDefault()` before calling the method                                                                 |
+| `.self`    | calls the method only if the `event.target` is the element itself                                                        |
+| `.capture` | bind the event handler in [capture](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) mode. |
+
+```xml
+<button t-on-click.stop="someMethod">Do something</button>
+```
+
+Note that modifiers can be combined (ex: `t-on-click.stop.prevent`), and that
+the order may matter. For instance `t-on-click.prevent.self` will prevent all
+clicks while `t-on-click.self.prevent` will only prevent clicks on the element
+itself.
+
+Finally, empty handlers are tolerated as they could be defined only to apply
+modifiers. For example,
+
+```xml
+<button t-on-click.stop="">Do something</button>
+```
+
+This will simply stop the propagation of the event.

doc/reference/hooks.md

@@ -0,0 +1,447 @@
+# 🦉 Hooks 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Example: Mouse Position](#example-mouse-position)
+- [Example: Autofocus](#example-autofocus)
+- [Reference](#reference)
+  - [One Rule](#one-rule)
+  - [`useState`](#usestate)
+  - [`onMounted`](#onmounted)
+  - [`onWillUnmount`](#onwillunmount)
+  - [`onWillPatch`](#onwillpatch)
+  - [`onPatched`](#onpatched)
+  - [`onWillStart`](#onwillstart)
+  - [`onWillUpdateProps`](#onwillupdateprops)
+  - [`useContext`](#usecontext)
+  - [`useRef`](#useref)
+  - [`useSubEnv`](#usesubenv)
+  - [`useExternalListener`](#useexternallistener)
+  - [`useStore`](#usestore)
+  - [`useDispatch`](#usedispatch)
+  - [`useGetters`](#usegetters)
+  - [Making customized hooks](#making-customized-hooks)
+
+## Overview
+
+Hooks were popularised by React as a way to solve the following issues:
+
+- help reusing stateful logic between components
+- help organizing code by feature in complex components
+- use state in functional components, without writing a class.
+
+Owl hooks serve the same purpose, except that they work for class components
+(note: React hooks do not work on class components, and maybe because of that,
+there seems to be the misconception that hooks are in opposition to class. This
+is clearly not true, as shown by Owl hooks).
+
+Hooks work beautifully with Owl components: they solve the problems mentioned
+above, and in particular, they are the perfect way to make your component
+reactive.
+
+## Example: mouse position
+
+Here is the classical example of a non trivial hook to track the mouse position.
+
+```js
+const { useState, onMounted, onWillUnmount } = owl.hooks;
+
+// We define here a custom behaviour: this hook tracks the state of the mouse
+// position
+function useMouse() {
+  const position = useState({ x: 0, y: 0 });
+
+  function update(e) {
+    position.x = e.clientX;
+    position.y = e.clientY;
+  }
+  onMounted(() => {
+    window.addEventListener("mousemove", update);
+  });
+  onWillUnmount(() => {
+    window.removeEventListener("mousemove", update);
+  });
+
+  return position;
+}
+
+// Main root component
+class App extends owl.Component {
+  static template = xml`
+    <div t-name="App">
+      <div>Mouse: <t t-esc="mouse.x"/>, <t t-esc="mouse.y"/></div>
+    </div>`;
+
+  // this hooks is bound to the 'mouse' property.
+  mouse = useMouse();
+}
+```
+
+Note that we use the prefix `use` for hooks, just like in React. This is just
+a convention.
+
+## Example: autofocus
+
+Hooks can be combined to create the desired effect. For example, the following
+hook combines the `useRef` hook with the `onPatched` and `onMounted` functions
+to create an easy way to focus an input whenever it appears in the DOM:
+
+```js
+function useAutofocus(name) {
+  let ref = useRef(name);
+  let isInDom = false;
+  function updateFocus() {
+    if (!isInDom && ref.el) {
+      isInDom = true;
+      ref.el.focus();
+    } else if (isInDom && !ref.el) {
+      isInDom = false;
+    }
+  }
+  onPatched(updateFocus);
+  onMounted(updateFocus);
+}
+```
+
+This hook takes the name of a valid `t-ref` directive, which should be present
+in the template. It then checks whenever the component is mounted or patched if
+the reference is not valid, and in this case, it will focus the node element.
+This hook can be used like this:
+
+```js
+class SomeComponent extends Component {
+  static template = xml`
+    <div>
+        <input />
+        <input t-ref="myinput"/>
+    </div>`;
+
+  constructor(...args) {
+    super(...args);
+    useAutofocus("myinput");
+  }
+}
+```
+
+## Reference
+
+### One rule
+
+There is only one rule: every hook for a component has to be called in the
+constructor (or in class fields):
+
+```js
+// ok
+class SomeComponent extends Component {
+  state = useState({ value: 0 });
+}
+
+// also ok
+class SomeComponent extends Component {
+  constructor(...args) {
+    super(...args);
+    this.state = useState({ value: 0 });
+  }
+}
+
+// not ok: this is executed after the constructor is called
+class SomeComponent extends Component {
+  async willStart() {
+    this.state = useState({ value: 0 });
+  }
+}
+```
+
+As you can see, the `useState` hook does not need to be given a reference to
+the component. This is possible because there is a way to get a reference to the
+current component: the `Component.current` static property is the reference to the
+component instance that is currently being created.
+
+Hooks need to be called in the constructor to ensure that this reference is
+properly set. This is also a good thing for performance reasons (Owl can use
+this to optimize its implementation), and for a clean architecture (this makes
+it easier for developers to understand what is really happening in a component).
+
+### `useState`
+
+The `useState` hook is certainly the most important hook for Owl components:
+this is what allows a component to be reactive, to react to state change.
+
+The `useState` hook has to be given an object or an array, and will return
+an observed version of it (using a `Proxy`).
+
+```javascript
+const { useState } = owl.hooks;
+
+class Counter extends owl.Component {
+  static template = xml`
+    <button t-on-click="increment">
+        Click Me! [<t t-esc="state.value"/>]
+    </button>`;
+
+  state = useState({ value: 0 });
+
+  increment() {
+    this.state.value++;
+  }
+}
+```
+
+It is important to remember that `useState` only works with objects or arrays. It
+is necessary, since Owl needs to react to a change in state.
+
+### `onMounted`
+
+`onMounted` is not a user hook, but is a building block designed to help make useful
+abstractions. `onMounted` registers a callback, which will be called when the component
+is mounted (see example on top of this page).
+
+### `onWillUnmount`
+
+`onWillUnmount` is not a user hook, but is a building block designed to help make useful
+abstractions. `onWillUnmount` registers a callback, which will be called when the component
+is unmounted (see example on top of this page).
+
+### `onWillPatch`
+
+`onWillPatch` is not a user hook, but is a building block designed to help make useful
+abstractions. `onWillPatch` registers a callback, which will be called just
+before the component patched.
+
+### `onPatched`
+
+`onPatched` is not a user hook, but is a building block designed to help make useful
+abstractions. `onPatched` registers a callback, which will be called just
+after the component patched.
+
+### `onWillStart`
+
+`onWillStart` is an asynchronous hook. This means that the function registered
+in the hook will be run just before the component is first rendered and can return a
+promise, to express the fact that it is an asynchronous operation.
+
+Note that if there are more than one `onWillStart` registered callback, then they
+will all be run in parallel.
+
+It can be used to load some initial data. For example, the following hook will
+automatically load some data from the server, and return an object that will
+be ready whenever the component is rendered:
+
+```js
+function useLoader() {
+  const component = Component.current;
+  const record = useState({});
+  onWillStart(async () => {
+    const recordId = component.props.id;
+    Object.assign(record, await fetchSomeRecord(recordId));
+  });
+  return record;
+}
+```
+
+Note that this example does not update the record value whenever props are
+updated. For that situation, we need to use the `onWillUpdateProps` hook.
+
+### `onWillUpdateProps`
+
+Just like `onWillStart`, `onWillUpdateProps` is an asynchronous hook. It is
+designed to be run whenever the component props are updated. This could be
+useful to perform some asynchronous task such as fetching updated data.
+
+```js
+function useLoader() {
+  const component = Component.current;
+  const record = useState({});
+
+  async function updateRecord(id) {
+    Object.assign(record, await fetchSomeRecord(id));
+  }
+
+  onWillStart(() => updateRecord(component.props.id));
+  onWillUpdateProps((nextProps) => updateRecord(nextProps.id));
+
+  return record;
+}
+```
+
+Note that if there are more than one `onWillUpdateProps` registered callback,
+then they will all be run in parallel.
+
+### `useContext`
+
+See [`useContext`](context.md#usecontext) for reference documentation.
+
+### `useRef`
+
+The `useRef` hook is useful when we need a way to interact with some inside part
+of a component, rendered by Owl. It can work either on a DOM node, or on a component,
+tagged by the `t-ref` directive:
+
+```xml
+<div>
+    <div t-ref="someDiv"/>
+    <SubComponent t-ref="someComponent"/>
+</div>
+```
+
+In this example, the component will be able to access the `div` and the component
+`SubComponent` using the `useRef` hook:
+
+```js
+class Parent extends Component {
+  subRef = useRef("someComponent");
+  divRef = useRef("someDiv");
+
+  someMethod() {
+    // here, if component is mounted, refs are active:
+    // - this.divRef.el is the div HTMLElement
+    // - this.subRef.comp is the instance of the sub component
+    // - this.subRef.el is the root HTML node of the sub component (i.e. this.subRef.comp.el)
+  }
+}
+```
+
+As shown by the example above, html elements are accessed by using the `el`
+key, and components references are accessed with `comp`.
+
+Notes:
+
+- if used on a component, the reference will be set in the `refs`
+  variable between `willPatch` and `patched`,
+- on a component, accessing `ref.el` will get the root node of the component.
+
+The `t-ref` directive also accepts dynamic values with string interpolation
+(like the [`t-attf-`](qweb_templating_language.md#dynamic-attributes) and
+`t-component` directives). For example,
+
+```xml
+<div t-ref="component_{{someCondition ? '1' : '2'}}"/>
+```
+
+Here, the references need to be set like this:
+
+```js
+this.ref1 = useRef("component_1");
+this.ref2 = useRef("component_2");
+```
+
+References are only guaranteed to be active while the parent component is mounted.
+If this is not the case, accessing `el` or `comp` on it will return `null`.
+
+### `useSubEnv`
+
+The environment is sometimes useful to share some common information between
+all components. But sometimes, we want to _scope_ that knowledge to a subtree.
+
+For example, if we have a form view component, maybe we would like to make some
+`model` object available to all sub components, but not to the whole application.
+This is where the `useSubEnv` hook may be useful: it lets a component add some
+information to the environment in a way that only the component and its children
+can access it:
+
+```js
+class FormComponent extends Component {
+  constructor(...args) {
+    super(...args);
+    const model = makeModel();
+    useSubEnv({ model });
+  }
+}
+```
+
+The `useSubEnv` takes one argument: an object which contains some key/value that
+will be added to the parent environment. Note that it will extend, not replace
+the parent environment. And of course, the parent environment will not be
+affected.
+
+### `useExternalListener`
+
+The `useExternalListener` hook helps solve a very common problem: adding and removing
+a listener on some target whenever a component is mounted/unmounted. For example,
+a dropdown menu (or its parent) may need to listen to a `click` event on `window`
+to be closed:
+
+```js
+useExternalListener(window, "click", this.closeMenu);
+```
+
+### `useStore`
+
+The `useStore` hook is the entry point for a component to connect to the store.
+See the [store documentation](store.md) for more information.
+
+### `useDispatch`
+
+The `useDispatch` hook is the way for components to get a reference to the store
+`dispatch` function. See the [store documentation](store.md) for more information.
+
+### `useGetters`
+
+The `useGetters` hook is the way for components to get a reference to the store
+getters. See the [store documentation](store.md) for more information.
+
+### Making customized hooks
+
+Hooks are a wonderful way to organize the code of a complex component by feature
+instead of by lifecycle methods. They are like mixins, except that they can be
+easily composed together.
+
+But, like every good things in life, hooks should be used with moderation. They are
+not the solution to every problem.
+
+- they may be overkill: if your component needs to perform some action specific
+  to itself (so, the specific code does not need to be shared), there is nothing
+  wrong with a simple class method:
+
+  ```js
+  // maybe overkill
+  class A extends Component {
+    constructor(...args) {
+      super(...args);
+      useMySpecificHook();
+    }
+  }
+
+  // ok
+  class B extends Component {
+    constructor(...args) {
+      super(...args);
+      this.performSpecificTask();
+    }
+  }
+  ```
+
+  Note that the second solution is easier to extend in sub components.
+
+- they may be harder to test: if a customized hook injects some external side
+  effect dependency, then it is harder to test without doing some non obvious
+  manipulation. For example, assume that we want to give a reference to a
+  router in a `useRouter` hook. We could do this:
+
+  ```js
+  const router = new Router(...);
+
+  function useRouter() {
+      return router;
+  }
+  ```
+
+  As you can see, this does not _hook_ into the internal of the component. It
+  simply returns a global object, which is difficult to mock.
+
+  A better way would be to do something like this: get the reference from the
+  environment.
+
+  ```js
+  function useRouter() {
+    return Component.current.env.router;
+  }
+  ```
+
+  This means that we give control to the application developer to create the
+  router, which is good, so they can set it up, subclass it, ... And then, to
+  test our components, we can just add a mock router in the environment.
+
+Note: the code above makes use of the `Component.current` property. This is the
+way hooks are able to get a reference to the component currently being created.

doc/reference/misc.md

@@ -0,0 +1,134 @@
+# 🦉 Miscellaneous 🦉
+
+## Content
+
+- [Portal](#portal)
+- [AsyncRoot](#asyncroot)
+
+## `Portal`
+
+### Overview
+
+The component `Portal` is meant to be used as a transparent way to 'teleport' a piece
+of DOM to the node represented by its sole `target` props.
+
+This component aims at helping the implementation of the needed infrastructure
+for modals (as in `bootstrap-modal`).
+
+### Usage
+
+The content it will teleport is defined within the `<Portal>` node and
+internally uses the `default` [Slot](slots.md).
+
+This slot must contain only **one** node, which in turn can have as many children as necessary.
+
+The element under which the content will be teleported is represented as a selector
+by the `target` props which only accepts a string as value.
+
+The `target` props only supports static selector, and is not meant to be passed to `Portal`
+as a variable. Namely, `<Portal target="'body'" />` is the intended use.
+By contrast, `<Portal target="state.target" />` is not supported.
+
+The component `Portal` has no particular state, rather it is meant to be a slave to its parent,
+and ultimately just a way for the parent to teleport a piece of its own DOM elsewhere.
+
+The `Portal`'s root node is always `<portal/>` and is placed where the teleported content
+_would have_ been. It is this element that the [teleported events](#expected-behaviors) are re-directed on.
+
+### Example
+
+The canonic use-case is to implement a Dialog, where a Component may choose to break the natural
+workflow to help the user put in some data, which it could use later on.
+
+JavaScript:
+
+```js
+const { Component } = owl;
+const { Portal } = owl.misc;
+
+class TeleportedComponent extends Component {}
+class App extends Component {
+  static components = { Portal, TeleportedComponent };
+}
+
+const app = new App();
+app.mount(document.body);
+```
+
+XML:
+
+```xml
+<templates>
+    <div t-name="TeleportedComponent">
+        <span>I will move soon enough</span>
+    </div>
+
+    <div t-name="App">
+        <span>I am like the rest of us</span>
+        <Portal target="'body'">
+            <TeleportedComponent />
+        </Portal>
+    </div>
+</templates>
+```
+
+In this example, the `Portal` component will teleport the `TeleportedComponent`'s `div` as a child of the `body`.
+`TeleportedComponent` is acting as a Dialog here.
+
+The resulting DOM will look like:
+
+```xml
+<body>
+    <div>
+        <span>I am like the rest of us</span>
+        <portal></portal>
+    </div>
+    <div>
+        <span>I will move soon enough</span>
+    </div>
+</body>
+```
+
+### Expected Behaviors
+
+The teleported piece is updated as any other `Component`'s DOM and in the same sequence.
+Namely the teleported piece will be updated in function of its parents components, and patched as
+a normal child.
+
+The [_business_ events](event_handling.md#business-dom-events) triggered by a child component will be stopped
+to not bubble outside of the `target`. They will, on the other hand, be re-directed onto the
+`Portal`'s root node and bubble up the DOM as if it were triggered by a regular child component.
+
+Beware that those re-directed events are copies of the original event.
+They have:
+
+- The same payload.
+- The same `originalComponent` than their original counterpart,
+  that is the actual Component that triggered it.
+- A **different** `target` property than their original counterpart.
+  The `target` of a re-directed event is necessarily the `Portal`'s root node.
+
+Pure DOM events do not follow this pattern and are free to bubble their natural, unaltered way
+up to the `body`.
+
+## `AsyncRoot`
+
+When this component is used, a new rendering sub tree is created, such that the
+rendering of that component (and its children) is not tied to the rendering of
+the rest of the interface. It can be used on an asynchronous component, to
+prevent it from delaying the rendering of the whole interface, or on a
+synchronous one, such that its rendering isn't delayed by other (asynchronous)
+components. Note that this directive has no effect on the first rendering, but
+only on subsequent ones (triggered by state or props changes).
+
+```xml
+<div t-name="ParentComponent">
+  <SyncChild />
+  <AsyncRoot>
+     <AsyncChild/>
+  </AsyncRoot>
+</div>
+```
+
+The `AsyncRoot` assumes that there is exactly one root node inside it. It can
+be a dom node or a component.

doc/reference/observer.md

@@ -0,0 +1,52 @@
+# 🦉 Observer 🦉
+
+Owl needs to be able to react to state changes. For example, whenever the state
+of a component is changed, Owl needs to rerender it. To help with that, there is
+an Observer class. Its job is to observe the state of an object (or array), and
+to react to any change. The observer is implemented with the native `Proxy`
+object. Note that this means that it will not work on older browsers.
+
+Note that the `Observer` is used by the `useState` and `useContext` hooks. This
+is the way most Owl applications will create observers. For the majority of
+use cases, there is no need to directly instantiate an observer.
+
+## Example
+
+For example, this code will display `update` in the console:
+
+```javascript
+const observer = new owl.Observer();
+observer.notifyCB = () => console.log("update");
+const obj = observer.observe({ a: { b: 1 } });
+
+obj.a.b = 2;
+```
+
+This example shows that an observer can observe nested properties.
+
+## Reference
+
+**observe** An observer can observe multiple values with the `observe` method.
+This method takes an object or an array as its argument and will return a proxy
+(which is mapped to the initial object/array). With this proxy, the observer
+can detect whenever any internal value is changed.
+
+**Registering a callback** Whenever an observer sees a state change, it will
+call its `notifyCB` method. No additional information is given to the callback.
+
+**deepRevNumber** Each observed value has an internal revision number, which
+is incremented every time the value is observed. Sometimes, it can be useful
+to obtain that number:
+
+```js
+const observer = new owl.Observer();
+const obj = observer.observe({ a: { b: 1 } });
+
+observer.deepRevNumber(obj.a); // 1
+obj.a.b = 2;
+
+observer.deepRevNumber(obj.a); // 2
+```
+
+The `deepRevNumber` can also return 0, which indicates that the value is not
+observed.

doc/reference/props.md

@@ -0,0 +1,97 @@
+# 🦉 Props 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Definition](#definition)
+- [Good Practices](#good-practices)
+- [Dynamic Props](#dynamic-props)
+
+## Overview
+
+In Owl, `props` (short for _properties_) is an object which contains every piece
+of data given to a component by its parent.
+
+```js
+class Child extends Component {
+  static template = xml`<div><t t-esc="props.a"/><t t-esc="props.b"/></div>`;
+}
+
+class Parent extends Component {
+  static template = xml`<div><ComponentA a="state.a" b="'string'"/></div>`;
+  static components = { Child };
+  state = useState({ a: "fromparent" });
+}
+```
+
+In this example, the `Child` component receives two props from its parent: `a`
+and `b`. They are collected into a `props` object by Owl, with each value being
+evaluated in the context of the parent. So, `props.a` is equal to `'fromparent'` and
+`props.b` is equal to `'string'`.
+
+Note that `props` is an object that only makes sense from the perspective of the
+child component.
+
+## Definition
+
+The `props` object is made of every attributes defined on the template, with the
+following exceptions:
+
+- every attribute starting with `t-` are not props (they are QWeb directives),
+- `style` and `class` attributes are excluded as well (they are applied by Owl on
+  the root element of the component).
+
+In the following example:
+
+```xml
+<div>
+    <ComponentA a="state.a" b="'string'"/>
+    <ComponentB t-if="state.flag" model="model"/>
+    <ComponentC style="color:red;" class="left-pane" />
+</div>
+```
+
+the `props` object contains the following keys:
+
+- for `ComponentA`: `a` and `b`,
+- for `ComponentB`: `model`,
+- for `ComponentC`: empty object
+
+## Good Practices
+
+A `props` object is a collection of values that come from the parent. As such,
+they are owned by the parent, and should never be modified by the child:
+
+```js
+class MyComponent extends Component {
+  constructor(parent, props) {
+    super(parent, props);
+    props.a.b = 43; // Never do that!!!
+  }
+}
+```
+
+Props should be considered readonly, from the perspective of the child component.
+If there is a need to modify them, then the request to update them should be
+sent to the parent (for example, with an event).
+
+Any value can go in a props. Strings, objects, classes, or even callbacks could
+be given to a child component (but then, in the case of callbacks, communicating
+with events seems more appropriate).
+
+## Dynamic Props
+
+The `t-props` directive can be used to specify totally dynamic props:
+
+```xml
+<div t-name="ParentComponent">
+    <Child t-props="some.obj"/>
+</div>
+```
+
+```js
+class ParentComponent {
+  static components = { Child };
+  some = { obj: { a: 1, b: 2 } };
+}
+```

doc/reference/props_validation.md

@@ -0,0 +1,103 @@
+# 🦉 Props Validation 🦉
+
+As an application becomes complex, it may be quite unsafe to define props in an informal way. This leads to two issues:
+
+- hard to tell how a component should be used, by looking at its code.
+- unsafe, it is easy to send wrong props into a component, either by refactoring a component, or one of its parents.
+
+A props type system solves both issues, by describing the types and shapes
+of the props. Here is how it works in Owl:
+
+- `props` key is a static key (so, different from `this.props` in a component instance)
+- it is optional: it is ok for a component to not define a `props` key.
+- props are validated whenever a component is created/updated
+- props are only validated in `dev` mode (see [config page](config.md#mode))
+- if a key does not match the description, an error is thrown
+- it validates keys defined in (static) `props`. Additional keys given by the
+  parent will cause an error.
+
+For example:
+
+```js
+class ComponentA extends owl.Component {
+    static props = ['id', 'url'];
+
+    ...
+}
+
+class ComponentB extends owl.Component {
+  static props = {
+    count: {type: Number},
+    messages: {
+      type: Array,
+      element: {type: Object, shape: {id: Boolean, text: String }
+    },
+   date: Date,
+   combinedVal: [Number, Boolean]
+  };
+
+  ...
+}
+```
+
+- it is an object or a list of strings
+- a list of strings is a simplified props definition, which only lists the name
+  of the props. Also, if the name ends with `?`, it is considered optional.
+- all props are by default required, unless they are defined with `optional: true`
+  (in that case, validation is only done if there is a value)
+- valid types are: `Number, String, Boolean, Object, Array, Date, Function`, and all
+  constructor functions (so, if you have a `Person` class, it can be used as a type)
+- arrays are homogeneous (all elements have the same type/shape)
+
+For each key, a `prop` definition is either a boolean, a constructor, a list of constructors, or an object:
+
+- a boolean: indicate that the props exists, and is mandatory.
+- a constructor: this should describe the type, for example: `id: Number` describe
+  the props `id` as a number
+- a list of constructors. In that case, this means that we allow more than one
+  type. For example, `id: [Number, String]` means that `id` can be either a string
+  or a number.
+- an object. This makes it possible to have more expressive definition. The following sub keys are then allowed (but not mandatory):
+  - `type`: the main type of the prop being validated
+  - `element`: if the type was `Array`, then the `element` key describes the type of each element in the array. If it is not set, then we only validate the array, not its elements,
+  - `shape`: if the type was `Object`, then the `shape` key describes the interface of the object. If it is not set, then we only validate the object, not its elements,
+  - `validate`: this is a function which should return a boolean to determine if
+    the value is valid or not. Useful for custom validation logic.
+
+Examples:
+
+```js
+  // only the existence of those 3 keys is documented
+  static props = ['message', 'id', 'date'];
+```
+
+```js
+  // size is optional
+  static props = ['message', 'size?'];
+```
+
+```js
+  static props = {
+    messageIds: {type: Array, element: Number},  // list of number
+    otherArr: {type: Array},   // just array. no validation is made on sub elements
+    otherArr2: Array,   // same as otherArr
+    someObj: {type: Object},  // just an object, no internal validation
+    someObj2: {
+      type: Object,
+      shape: {
+        id: Number,
+        name: {type: String, optional: true},
+        url: String
+      ]},    // object, with keys id (number), name (string, optional) and url (string)
+    someFlag: Boolean,     // a boolean, mandatory (even if `false`)
+    someVal: [Boolean, Date],   // either a boolean or a date
+    otherValue: true,     // indicates that it is a prop
+    kindofsmallnumber: {
+      type: Number,
+      validate: n => (0 <= n && n <= 10)
+    },
+    size: {
+      validate:  e => ["small", "medium", "large"].includes(e)
+    },
+  };
+```

doc/reference/qweb_engine.md

@@ -0,0 +1,153 @@
+# 🦉 QWeb Engine 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Reference](#reference)
+
+## Overview
+
+[QWeb](https://www.odoo.com/documentation/13.0/reference/qweb.html) is the primary
+templating engine used by Odoo. The QWeb class in the OWL project is an
+implementation of that specification with a few interesting points:
+
+- it compiles templates into functions that output a virtual DOM instead of a
+  string. This is necessary for the component system.
+- it has a few extra directives: `t-component`, `t-on`, ...
+
+We present in this section the engine, not the templating language.
+
+## Reference
+
+This section is about the javascript code that implements the `QWeb` specification.
+Owl exports a `QWeb` class in `owl.QWeb`. To use it, it just needs to be
+instantiated:
+
+```js
+const qweb = new owl.QWeb();
+```
+
+Its API is quite simple:
+
+- **`constructor(config)`**: constructor. Takes an optional configuration object
+  with an optional `templates` string to add initial
+  templates (see `addTemplates` for more information on format of the string)
+  and an optional `translateFn` translate function (see the section on
+  [translations](#translations)).
+
+  ```js
+  const qweb = new owl.QWeb({ templates: TEMPLATES, translateFn: _t });
+  ```
+
+- **`addTemplate(name, xmlStr, allowDuplicate)`**: add a specific template.
+
+  ```js
+  qweb.addTemplate("mytemplate", "<div>hello</div>");
+  ```
+
+  If the optional `allowDuplicate` is set to `true`, then `QWeb` will simply
+  ignore templates added for a second time. Otherwise, `QWeb` will crash.
+
+- **`addTemplates(xmlStr)`**: add a list of templates (identified by `t-name`
+  attribute).
+
+  ```js
+  const TEMPLATES = `
+    <templates>
+      <div t-name="App" class="main">main</div>
+      <div t-name="OtherComponent">other component</div>
+    </templates>`;
+  qweb.addTemplates(TEMPLATES);
+  ```
+
+- **`render(name, context, extra)`**: renders a template. This returns a `vnode`,
+  which is a virtual representation of the DOM (see [vdom doc](../miscellaneous/vdom.md)).
+
+  ```js
+  const vnode = qweb.render("App", component);
+  ```
+
+- **`renderToString(name, context)`**: renders a template, but returns an html
+  string.
+
+  ```js
+  const str = qweb.renderToString("someTemplate", somecontext);
+  ```
+
+- **`registerTemplate(name, template)`**: static function to register a global
+  QWeb template. This is useful for commonly used components accross the
+  application, and for making a template available to an application without
+  having a reference to the actual QWeb instance.
+
+  ```js
+  QWeb.registerTemplate("mytemplate", `<div>some template</div>`);
+  ```
+
+- **`registerComponent(name, Component)`**: static function to register an OWL Component
+  to QWeb's global registry. Globally registered Components can be used in
+  templates (see the `t-component` directive). This is useful for commonly used
+  components accross the application.
+
+  ```js
+  class Dialog extends owl.Component { ... }
+  QWeb.registerComponent("Dialog", Dialog);
+
+  ...
+
+  class ParentComponent extends owl.Component { ... }
+  qweb.addTemplate("ParentComponent", "<div><Dialog/></div>");
+  ```
+
+In some way, a `QWeb` instance is the core of an Owl application. It is the only
+mandatory element of an [environment](environment.md). As such, it
+has an extra responsibility: it can act as an event bus for internal communication
+between Owl classes. This is the reason why `QWeb` actually extends [EventBus](event_bus.md).
+
+### Translations
+
+take care of this and "cherry-pick" 8464a1b04e7469434f9dcb3d68a543f58cb61b8e
+
+If properly setup, Owl QWeb engine can translate all rendered templates. To do
+so, it needs a translate function, which takes a string and returns a string.
+
+For example:
+
+```js
+const translations = {
+  hello: "bonjour",
+  yes: "oui",
+  no: "non",
+};
+const translateFn = (str) => translations[str] || str;
+
+const qweb = new QWeb({ translateFn });
+```
+
+Once setup, all rendered templates will be translated using `translateFn`:
+
+- each text node will be replaced with its translation,
+- each of the following attribute values will be translated as well: `title`,
+  `placeholder`, `label` and `alt`,
+- translating text nodes can be disabled with the special attribute `t-translation`,
+  if its value is `off`.
+
+So, with the above `translateFn`, the following templates:
+
+```xml
+<div>hello</div>
+<div t-translation="off">hello</div>
+<div>Are you sure?</div>
+<input placeholder="hello" other="yes"/>
+```
+
+will be rendered as:
+
+```xml
+<div>bonjour</div>
+<div>hello</div>
+<div>Are you sure?</div>
+<input placeholder="bonjour" other="yes"/>
+```
+
+Note that the translation is done during the compilation of the template, not
+when it is rendered.

doc/reference/qweb_templating_language.md

@@ -0,0 +1,576 @@
+# 🦉 QWeb Templating Language🦉
+
+## Content
+
+- [Overview](#overview)
+- [Directives](#directives)
+- [Reference](#reference)
+  - [White Spaces](#white-spaces)
+  - [Root Nodes](#root-nodes)
+  - [Expression Evaluation](#expression-evaluation)
+  - [Static html Nodes](#static-html-nodes)
+  - [Outputting Data](#outputting-data)
+  - [Setting Variables](#setting-variables)
+  - [Conditionals](#conditionals)
+  - [Dynamic Attributes](#dynamic-attributes)
+  - [Loops](#loops)
+  - [Rendering Sub Templates](#rendering-sub-templates)
+  - [Dynamic Sub Templates](#dynamic-sub-templates)
+  - [Translations](#translations)
+  - [Debugging](#debugging)
+
+## Overview
+
+[QWeb](https://www.odoo.com/documentation/13.0/reference/qweb.html) is the primary
+templating engine used by Odoo. It is based on the XML format, and used
+mostly to generate HTML. In OWL, QWeb templates are compiled into functions that
+generate a virtual dom representation of the HTML.
+
+```xml
+<div>
+    <span t-if="somecondition">Some string</span>
+    <ul t-else="">
+        <li t-foreach="messages" t-as="message">
+            <t t-esc="message"/>
+        </li>
+    </ul>
+</div>
+```
+
+Template directives are specified as XML attributes prefixed with `t-`, for
+instance `t-if` for conditionals, with elements and other attributes being
+rendered directly.
+
+To avoid element rendering, a placeholder element `<t>` is also available, which
+executes its directive but doesn’t generate any output in and of itself.
+
+We present in this section the templating language, including its Owl specific
+extensions.
+
+## Directives
+
+For reference, here is a list of all standard QWeb directives:
+
+| Name                           | Description                                                    |
+| ------------------------------ | -------------------------------------------------------------- |
+| `t-esc`                        | [Outputting safely a value](#outputting-data)                  |
+| `t-raw`                        | [Outputting value, without escaping](#outputting-data)         |
+| `t-set`, `t-value`             | [Setting variables](#setting-variables)                        |
+| `t-if`, `t-elif`, `t-else`,    | [conditionally rendering](#conditionals)                       |
+| `t-foreach`, `t-as`            | [Loops](#loops)                                                |
+| `t-att`, `t-attf-*`, `t-att-*` | [Dynamic attributes](#dynamic-attributes)                      |
+| `t-call`                       | [Rendering sub templates](#rendering-sub-templates)            |
+| `t-debug`, `t-log`             | [Debugging](#debugging)                                        |
+| `t-translation`                | [Disabling the translation of a node](#translations)           |
+| `t-name`                       | [Defining a template (not really a directive)](qweb_engine.md) |
+
+The component system in Owl requires additional directives, to express various
+needs. Here is a list of all Owl specific directives:
+
+| Name                     | Description                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `t-component`, `t-props` | [Defining a sub component](component.md#composition)                            |
+| `t-ref`                  | [Setting a reference to a dom node or a sub component](component.md#references) |
+| `t-key`                  | [Defining a key (to help virtual dom reconciliation)](#loops)                   |
+| `t-on-*`                 | [Event handling](event_handling.md)                                             |
+| `t-transition`           | [Defining an animation](animations.md#css-transitions)                          |
+| `t-slot`                 | [Rendering a slot](slots.md)                                                    |
+| `t-model`                | [Form input bindings](component.md#form-input-bindings)                         |
+
+## Reference
+
+### White Spaces
+
+White spaces in a template are handled in a special way:
+
+- consecutive whitespaces are always condensed to a single whitespace
+- if a whitespace-only text node contains a linebreak, it is ignored
+- the previous rules do not apply if we are in a `<pre>` tag
+
+### Root Nodes
+
+For many reasons, Owl QWeb templates should have a single root node. More
+precisely, the result of a template rendering should have a single root node:
+
+```xml
+<!–– not ok: two root nodes ––>
+<t>
+    <div>foo</div>
+    <div>bar</div>
+</t>
+
+<!–– ok: result has one single root node ––>
+<t>
+    <div t-if="someCondition">foo</div>
+    <span t-else="">bar</span>
+</t>
+```
+
+Extra root nodes will actually be ignored (even though they will be rendered
+in memory).
+
+Note: this does not apply to subtemplates (see the `t-call` directive). In that
+case, they will be inlined in the main template, and can actually have many
+root nodes.
+
+### Expression Evaluation
+
+QWeb expressions are strings that will be processed at compile time. Each variable in
+the javascript expression will be replaced with a lookup in the context (so, the
+component). For example, `a + b.c(d)` will be converted into:
+
+```js
+context["a"] + context["b"].c(context["d"]);
+```
+
+It is useful to explain the various rules that apply on these expressions:
+
+1. it should be a simple expression which returns a value. It cannot be a statement.
+
+   ```xml
+   <div><p t-if="1 + 2 === 3">ok</p></div>
+   ```
+
+   is valid, but the following is not valid:
+
+   ```xml
+   <div><p t-if="console.log(1)">NOT valid</p></div>
+   ```
+
+2. it can use anything in the rendering context (typically, the component):
+
+   ```xml
+   <p t-if="user.birthday === today()">Happy bithday!</p>
+   ```
+
+   is valid, and will read the `user` object from the context, and call the
+   `today` function.
+
+3. it can use a few special operators to avoid using symbols such as `<`, `>`,
+   `&` or `|`. This is useful to make sure that we still write valid XML.
+
+   | Word  | replaced with |
+   | ----- | ------------- |
+   | `and` | `&&`          |
+   | `or`  | `\|\|`        |
+   | `gt`  | `>`           |
+   | `gte` | `>=`          |
+   | `lt`  | `<`           |
+   | `lte` | `<=`          |
+
+   So, one can write this:
+
+   ```xml
+   <div><p t-if="10 + 2 gt 5">ok</p></div>
+   ```
+
+### Static Html Nodes
+
+Normal, regular html nodes are rendered into themselves:
+
+```xml
+  <div>hello</div> <!–– rendered as itself ––>
+```
+
+### Outputting Data
+
+The `t-esc` directive is necessary whenever you want to add a dynamic text
+expression in a template. The text is escaped to avoid security issues.
+
+```xml
+<p><t t-esc="value"/></p>
+```
+
+rendered with the value `value` set to `42` in the rendering context yields:
+
+```html
+<p>42</p>
+```
+
+The `t-raw` directive is almost the same as `t-esc`, but without the escaping.
+This is mostly useful to inject a raw html string somewhere. Obviously, this
+is unsafe to do in general, and should only be used for strings known to be safe.
+
+```xml
+<p><t t-raw="value"/></p>
+```
+
+rendered with the value `value` set to `<span>foo</span>` in the rendering context yields:
+
+```html
+<p><span>foo</span></p>
+```
+
+Note that since the content of the expression is not known beforehand, the `t-raw`
+directive has to parse the html (and convert it to a virtual dom structure) for
+each rendering. So, it will be much slower than a regular template. It is
+therefore advised to limit the use of `t-raw` whenever possible.
+
+### Setting Variables
+
+QWeb allows creating variables from within the template, to memoize a computation (to use it multiple times), give a piece of data a clearer name, ...
+
+This is done via the `t-set` directive, which takes the name of the variable to create. The value to set can be provided in two ways:
+
+1. a `t-value` attribute containing an expression, and the result of its
+   evaluation will be set:
+
+   ```xml
+   <t t-set="foo" t-value="2 + 1"/>
+   <t t-esc="foo"/>
+   ```
+
+   will print `3`. Note that the evaluation is done at rendering time, not at
+   compilte time.
+
+2. if there is no `t-value` attribute, the node’s body is saved and its value is
+   set as the variable’s value:
+
+   ```xml
+   <t t-set="foo">
+       <li>ok</li>
+   </t>
+   <t t-esc="foo"/>
+   ```
+
+   will generate `&lt;li&gt;ok&lt;/li&gt;` (the content is escaped as we used the `t-esc` directive)
+
+The `t-set` directive acts like a regular variable in most programming language.
+It is lexically scoped (inner nodes are sub scopes), can be shadowed, ...
+
+### Conditionals
+
+The `t-if` directive is useful to conditionally render something. It evaluates
+the expression given as attribute value, and then acts accordingly.
+
+```xml
+<div>
+    <t t-if="condition">
+        <p>ok</p>
+    </t>
+</div>
+```
+
+The element is rendered if the condition (evaluated with the current rendering
+context) is true:
+
+```xml
+<div>
+    <p>ok</p>
+</div>
+```
+
+but if the condition is false it is removed from the result:
+
+```xml
+<div>
+</div>
+```
+
+The conditional rendering applies to the bearer of the directive, which does not
+have to be `<t>`:
+
+```xml
+<div>
+    <p t-if="condition">ok</p>
+</div>
+```
+
+will give the same results as the previous example.
+
+Extra conditional branching directives `t-elif` and `t-else` are also available:
+
+```xml
+<div>
+    <p t-if="user.birthday == today()">Happy bithday!</p>
+    <p t-elif="user.login == 'root'">Welcome master!</p>
+    <p t-else="">Welcome!</p>
+</div>
+```
+
+### Dynamic Attributes
+
+One can use the `t-att-` directive to add dynamic attributes. Its main use is to
+evaluate an expression (at rendering time) and bind an attribute to its result:
+
+For example, if we have `id` set to 32 in the rendering context,
+
+```xml
+<div t-att-data-action-id="id"/> <!-- result: <div data-action-id="32"></div> -->
+```
+
+If an expression evaluates to a falsy value, it will not be set at all:
+
+```xml
+<div t-att-foo="false"/>  <!-- result: <div></div> -->
+```
+
+It is sometimes convenient to format an attribute with string interpolation. In
+that case, the `t-attf-` directive can be used. It is useful when we need to mix
+literal and dynamic elements, such as css classes.
+
+```xml
+<div t-attf-foo="a {{value1}} is {{value2}} of {{value3}} ]"/>
+<!-- result if values are set to 1,2 and 3: <div foo="a 0 is 1 of 2 ]"></div> -->
+```
+
+If we need completely dynamic attribute names, then there is an additional
+directive: `t-att`, which takes either an object (with keys mapping to their
+values) or a pair `[key, value]`. For example:
+
+```xml
+<div t-att="{'a': 1, 'b': 2}"/> <!-- result: <div a="1" b="2"></div> -->
+
+<div t-att="['a', 'b']"/> <!-- <div a="b"></div> -->
+```
+
+### Loops
+
+QWeb has an iteration directive `t-foreach` which take an expression returning the
+collection to iterate on, and a second parameter `t-as` providing the name to use
+for the current item of the iteration:
+
+```xml
+<t t-foreach="[1, 2, 3]" t-as="i">
+    <p><t t-esc="i"/></p>
+</t>
+```
+
+will be rendered as:
+
+```xml
+<p>1</p>
+<p>2</p>
+<p>3</p>
+```
+
+Like conditions, `t-foreach` applies to the element bearing the directive’s attribute, and
+
+```xml
+<p t-foreach="[1, 2, 3]" t-as="i">
+    <t t-esc="i"/>
+</p>
+```
+
+is equivalent to the previous example.
+
+`t-foreach` can iterate on an array (the current item will be the current value)
+or an object (the current item will be the current key).
+
+In addition to the name passed via t-as, `t-foreach` provides a few other
+variables for various data points (note: `$as` will be replaced with the name
+passed to `t-as`):
+
+- `$as_value`: the current iteration value, identical to `$as` for lists and
+  integers, but for objects, it provides the value (where `$as` provides the key)
+- `$as_index`: the current iteration index (the first item of the iteration has index 0)
+- `$as_first`: whether the current item is the first of the iteration
+  (equivalent to `$as_index == 0`)
+- `$as_last`: whether the current item is the last of the iteration
+  (equivalent to `$as_index + 1 == $as_size`), requires the iteratee’s size be
+  available
+
+These extra variables provided and all new variables created into the `t-foreach`
+are only available in the scope of the `t-foreach`. If the variable exists outside
+the context of the `t-foreach`, the value is copied at the end of the foreach
+into the global context.
+
+```xml
+<t t-set="existing_variable" t-value="false"/>
+<!-- existing_variable now False -->
+
+<p t-foreach="Array(3)" t-as="i">
+    <t t-set="existing_variable" t-value="true"/>
+    <t t-set="new_variable" t-value="true"/>
+    <!-- existing_variable and new_variable now true -->
+</p>
+
+<!-- existing_variable always true -->
+<!-- new_variable undefined -->
+```
+
+Even though Owl tries to be as declarative as possible, the DOM does not fully
+expose its state declaratively in the DOM tree. For example, the scrolling state,
+the current user selection, the focused element or the state of an input are not
+set as attribute in the DOM tree. This is why we use a virtual dom
+algorithm to keep the actual DOM node as much as possible.
+
+However, in some situations, this is not enough, and we need to help Owl decide
+if an element is actually the same, or is a different element with the same
+properties.
+
+Consider the following situation: we have a list of two items `[{text: "a"}, {text: "b"}]`
+and we render them in this template:
+
+```xml
+<p t-foreach="items" t-as="item"><t t-esc="item.text"/></p>
+```
+
+The result will be two `<p>` tags with text `a` and `b`. Now, if we swap them,
+and rerender the template, Owl needs to know what the intent is:
+
+- should Owl actually swap the DOM nodes,
+- or should it keep the DOM nodes, but with an updated text content?
+
+This might look trivial, but it actually matters. These two possibilities lead
+to different results in some cases. For example, if the user selected the text
+of the first `p`, swapping them will keep the selection while updating the
+text content will not.
+
+There are many other cases where this is important: `input` tags with their
+value, css classes and animations, scroll position...
+
+So, the `t-key` directive is used to give an identity to an element. It allows
+Owl to understand if different elements of a list are actually different or not.
+
+The above example could be modified by adding an ID: `[{id: 1, text: "a"}, {id: 2, text: "b"}]`.
+Then, the template could look like this:
+
+```xml
+<p t-foreach="items" t-as="item" t-key="item.id"><t t-esc="item.text"/></p>
+```
+
+The `t-key` directive is useful for lists (`t-foreach`). A key should be
+a unique number or string (objects will not work: they will be cast to the
+`"[object Object]"` string, which is obviously not unique).
+
+Also, the key can be set on a `t` tag or on its children. The following variations
+are all equivalent:
+
+```xml
+<p t-foreach="items" t-as="item" t-key="item.id">
+  <t t-esc="item.text"/>
+</p>
+
+<t t-foreach="items" t-as="item" t-key="item.id">
+  <p t-esc="item.text"/>
+</t>
+
+<t t-foreach="items" t-as="item">
+  <p t-key="item.id" t-esc="item.text"/>
+</t>
+```
+
+If there is no `t-key` directive, Owl will use the index as a default key.
+
+Note: the `t-foreach` directive only accepts arrays (lists) or objects. It does
+not work with other iterables, such as `Set`. However, it is only a matter of
+using the `...` javascript operator. For example:
+
+```xml
+<t t-foreach="...items" t-as="item">...</t>
+```
+
+The `...` operator will convert the `Set` (or any other iterables) into a list,
+which will work with Owl QWeb.
+
+### Rendering Sub Templates
+
+QWeb templates can be used for top level rendering, but they can also be used
+from within another template (to avoid duplication or give names to parts of
+templates), using the `t-call` directive:
+
+```xml
+<div t-name="other-template">
+    <p><t t-value="var"/></p>
+</div>
+
+<div t-name="main-template">
+    <t t-set="var" t-value="owl"/>
+    <t t-call="other-template"/>
+</div>
+```
+
+will be rendered as `<div><p>owl</p></div>`. This example shows that the sub
+template is rendered with the execution context of the parent. The sub template
+is actually inlined in the main template, but in a sub scope: variables defined
+in the sub template do not escape.
+
+Sometimes, one might want to pass information to the sub template. In that case,
+the content of the body of the `t-call` directive is available as a special
+magic variable `0`:
+
+```xml
+<t t-name="other-template">
+    This template was called with content:
+    <t t-raw="0"/>
+</t>
+
+<div t-name="main-template">
+    <t t-call="other-template">
+        <em>content</em>
+    </t>
+</div>
+```
+
+will result in :
+
+```xml
+<div>
+    This template was called with content:
+    <em>content</em>
+</div>
+```
+
+This can be used to define variables scoped to a sub template:
+
+```xml
+<t t-call="other-template">
+    <t t-set="var" t-value="1"/>
+</t>
+<!-- "var" does not exist here -->
+```
+
+### Dynamic sub templates
+
+The `t-call` directive can also be used to dynamically call a sub template,
+using string interpolation. For example:
+
+```xml
+<div t-name="main-template">
+    <t t-call="{{template}}">
+        <em>content</em>
+    </t>
+</div>
+```
+
+Here, the name of the template is obtained from the `template` value in the
+template rendering context.
+
+### Translations
+
+By default, QWeb specify that templates should be translated. If this behaviour
+is not wanted, there is a `t-translation` directive which can turn off
+translations (if it is set to the `off` value), with the following rules:
+
+- each text node will be replaced with its translation,
+- each of the following attribute values will be translated as well: `title`,
+  `placeholder`, `label` and `alt`,
+- translating text nodes can be disabled with the special attribute `t-translation`,
+  if its value is `off`.
+
+See [here](qweb_engine.md#translations) for more information on how to setup a
+translate function in Owl QWeb.
+
+### Debugging
+
+The javascript QWeb implementation provides two useful debugging directives:
+
+`t-debug` adds a debugger statement during template rendering:
+
+```xml
+<t t-if="a_test">
+    <t t-debug=""/>
+</t>
+```
+
+will stop execution if the browser dev tools are open.
+
+`t-log` takes an expression parameter, evaluates the expression during rendering and logs its result with console.log:
+
+```xml
+<t t-set="foo" t-value="42"/>
+<t t-log="foo"/>
+```
+
+will print 42 to the console.

doc/reference/router.md

@@ -0,0 +1,183 @@
+# 🦉 Router 🦉
+
+Remove?
+
+## Content
+
+- [Overview](#overview)
+- [Example](#example)
+- [Reference](#reference)
+  - [Route Definition](#route-definition)
+  - [Router](#router)
+  - [Navigation Guards](#navigation-guards)
+  - [RouteComponent](#routecomponent)
+  - [Link](#link)
+
+## Overview
+
+It is often useful to organize an application around urls. If the application is
+a single page application, then we need a way to manage those urls in the browser.
+This is why there are many different routers for different frameworks. A generic
+router can do the job just fine, but a specialized router for Owl can give a
+better developer experience.
+
+The Owl router support the following features:
+
+- `history` or `hash` mode
+- declarative routes
+- route redirection
+- navigation guards
+- parameterized routes
+- a `<Link/>` component
+- a `<RouteComponent/>` component
+
+Note that it is still in early stage of developments, and there are probably
+still some issues.
+
+## Example
+
+To use the Owl router, there are some steps that needs to be done:
+
+- declare some routes
+- create a router
+- add it to the environment
+
+```js
+async function protectRoute({ env, to }) {
+  if (!env.session.authUser) {
+    env.session.setNextRoute(to.name);
+    return { to: "SIGN_IN" };
+  }
+  return true;
+}
+
+export const ROUTES = [
+  { name: "LANDING", path: "/", component: Landing },
+  { name: "TASK", path: "/tasks/{{id}}", component: Task },
+  { name: "SIGN_UP", path: "/signup", component: SignUp },
+  { name: "SIGN_IN", path: "/signin", component: SignIn },
+  { name: "ADMIN", path: "/admin", component: Admin, beforeRouteEnter: protectRoute },
+  { name: "ACCOUNT", path: "/account", component: Account, beforeRouteEnter: protectRoute },
+  { name: "UNKNOWN", path: "*", redirect: { to: "LANDING" } }
+];
+
+function makeEnvironment() {
+    ...
+    const env = { qweb };
+    env.session = new Session(env);
+    env.router = new owl.router.Router(env, ROUTES);
+    await env.router.start();
+    return env;
+}
+
+App.env = makeEnvironment();
+// create root component here
+```
+
+Notice that the router needs to be started. This is an asynchronous operation
+because it needs to apply the potential navigation guards on the current route
+(which may or may not mean that the application is redirected to another route).
+
+## Reference
+
+### Route definition
+
+A route need to be defined as an object with the following keys:
+
+- `name` (optional): a (unique) string useful to identify the current route. If not
+  given, it will be assigned an automatic name,
+- `path`: a string describing the url. It can be static: `/admin` or dynamic: `/users/{{id}}`.
+  It also can be `*`, to catch all remaining routes.
+- `component` (optional): an Owl component that will be used by the `t-routecomponent`
+  directive if the route is active
+- `redirect` (optional): should be destination object (with optional keys `path`, `to` and `params`) if given, the application will be redirected to the destination whenever we match this route
+- `beforeRouteEnter`: defines a [navigation guard](#navigation-guards).
+
+### `Router`
+
+The `Router` constructor takes three arguments:
+
+- `env`: a valid environment,
+- a list of routes,
+- an optional object (with the only key `mode` which can be `history` (default
+  value) or `hash`).
+
+`history` will use the browser [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) as the mechanism to manage URL.\
+Example: `https://yourdomain.tld/my_custom_route`.\
+For this mechanism to work, you need a way to configure your web server accordingly.
+
+`hash` will manipulate the hash of the URL.\
+Example: `https://yourdomain.tld/index.html#/my_custom_route`.
+
+```js
+const ROUTES = [...];
+const router = new owl.router.Router(env, ROUTES, {mode: 'history'});
+```
+
+Note that the route are defined in a list, and the order matters: the router
+tries to find a match by going down the list.
+
+The router needs to be added to the environment in the `router` sub key.
+
+Once a router is created, it needs to be started. This is necessary to initialize
+its current state to the current URL (and also, to potentially apply any
+navigation guards and/or redirecting).
+
+```js
+await router.start();
+```
+
+Once started, the router will keep track of the current url and reflect its
+value in two keys:
+
+- `router.currentRoute`
+- `router.currentParams`
+
+The router also has a `navigate` method, useful to programmatically change the
+application to another state (and the url):
+
+```js
+router.navigate({ to: "USER", params: { id: 51 } });
+```
+
+### Navigation Guards
+
+Navigation guards are very useful to be able to execute some business logic/
+perform some actions or redirect to other routes whenever the application is
+entering a new route. For example, the following guard checks if there is an
+authenticated user, and if it is not the case, redirect to the sign in route.
+
+```js
+async function protectRoute({ env, to }) {
+  if (!env.session.authUser) {
+    env.session.setNextRoute(to.name);
+    return { to: "SIGN_IN" };
+  }
+  return true;
+}
+```
+
+A navigation guard is a function that returns a promise, which either resolves
+to `true` (the navigation is accepted), or to another destination object.
+
+### `RouteComponent`
+
+The `RouteComponent` component directs Owl to render the component associated
+to the currently active route (if any):
+
+```xml
+<div t-name="App">
+    <NavBar />
+    <RouteComponent />
+</div>
+```
+
+### `Link`
+
+The `Link` component is a Owl component which render as a `<a>` tag with any
+content. It will compute the proper href from its props, and allow Owl to
+properly navigate to a given url if clicked on it.
+
+```xml
+<Link to="'HOME'">Home</Link>
+```

doc/reference/slots.md

@@ -0,0 +1,96 @@
+# 🦉 Slots 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Example](#example)
+- [Reference](#reference)
+
+## Overview
+
+Owl is a template based component system. There is therefore a need to be able
+to make generic components. For example, imagine a generic `Dialog`
+component, which is able to display some arbitrary content.
+
+Obviously, we want to use this component everywhere in our application, to
+display various different content. The `Dialog` component is technically the
+owner of its content, but is only a container. The user of the `Dialog` is
+the component that want to _inject_ something inside the `Dialog`. This is
+exactly what slots are for.
+
+## Example
+
+To make generic components, it is useful to be able for a parent component to _inject_
+some sub template, but still be the owner. For example, a generic dialog component
+will need to render some content, some footer, but with the parent as the
+rendering context.
+
+```xml
+<div t-name="Dialog" class="modal">
+  <div class="modal-title"><t t-esc="props.title"/></div>
+  <div class="modal-content">
+    <t t-slot="content"/>
+  </div>
+  <div class="modal-footer">
+    <t t-slot="footer"/>
+  </div>
+</div>
+```
+
+Slots are defined by the caller, with the `t-set-slot` directive:
+
+```xml
+<div t-name="SomeComponent">
+  <div>some component</div>
+  <Dialog title="Some Dialog">
+    <t t-set-slot="content">
+      <div>hey</div>
+    </t>
+    <t t-set-slot="footer">
+      <button t-on-click="doSomething">ok</button>
+    </t>
+  </Dialog>
+</div>
+```
+
+In this example, the component `Dialog` will render the slots `content` and `footer`
+with its parent as rendering context. This means that clicking on the button
+will execute the `doSomething` method on the parent, not on the dialog.
+
+Note: Owl previously used the `t-set` directive to define the content of a slot.
+This is deprecated and should no longer be used in new code.
+
+## Reference
+
+Default slot: the first element inside the component which is not a named slot will
+be considered the `default` slot. For example:
+
+```xml
+<div t-name="Parent">
+  <Child>
+    <span>some content</span>
+  </Child>
+</div>
+
+<div t-name="Child">
+  <t t-slot="default"/>
+</div>
+```
+
+Default content: slots can define a default content, in case the parent did not define them:
+
+```xml
+<div t-name="Parent">
+  <Child/>
+</div>
+
+<span t-name="Child">
+  <t t-slot="default">default content</t>
+</span>
+<!-- will be rendered as: <div><span>default content</span></div> -->
+```
+
+Rendering context: the content of the slots is actually rendered with the
+rendering context corresponding to where it was defined, not where it is
+positioned. This allows the user to define event handlers that will be bound
+to the correct component (usually, the grandparent of the slot content).

doc/reference/store.md

@@ -0,0 +1,349 @@
+# 🦉 Store 🦉
+
+## Content
+
+- [Overview](#overview)
+- [Example](#example)
+- [Reference](#reference)
+  - [Store](#store)
+  - [Actions](#actions)
+  - [Getters](#getters)
+  - [Connecting a Component](#connecting-a-component)
+  - [`useStore`](#usestore)
+  - [`useDispatch`](#usedispatch)
+  - [`useGetters`](#usegetters)
+  - [Semantics](#semantics)
+  - [Good Practices](#good-practices)
+
+## Overview
+
+Managing the state in an application is not an easy task. In some cases, the
+state of an application can be part of the component tree, in a natural way.
+However, there are situations where some parts of the state need to be displayed
+in various parts of the user interface, and then, it is not obvious which
+component should own which part of the state.
+
+Owl's solution to this issue is a centralized store. It is a class that owns
+some (or all) state, and lets the developer update it in a structured way, with
+`actions`. Owl components can then connect to the store to read their relevant
+state, and they will be rerendered if the state is updated.
+
+Note: Owl store is inspired by React Redux and VueX.
+
+## Example
+
+Here is what a simple store looks like:
+
+```js
+const actions = {
+  addTodo({ state }, message) {
+    state.todos.push({
+      id: state.nextId++,
+      message,
+      isCompleted: false,
+    });
+  },
+};
+
+const state = {
+  todos: [],
+  nextId: 1,
+};
+
+const store = new owl.Store({ state, actions });
+store.on("update", null, () => console.log(store.state));
+
+// updating the state
+store.dispatch("addTodo", "fix all bugs");
+```
+
+This example shows how a store can be defined and used. Note that in most cases,
+actions will be dispatched by connected components.
+
+## Reference
+
+### `Store`
+
+The store is a simple [`owl.EventBus`](event_bus.md) that triggers `update` events
+whenever its state is changed. Note that these events are triggered only after a
+microtask tick, so only one event will be triggered for any number of state changes in a
+call stack.
+
+Also, it is important to mention that the state is observed (with an `owl.Observer`),
+which is the reason why it is able to know if it was changed. See the
+[Observer](observer.md)'s documentation for more details.
+
+The `Store` class is quite small. It has two public methods:
+
+- its constructor
+- `dispatch`
+
+The constructor takes a configuration object with four (optional) keys:
+
+- the initial state
+- the actions
+- the getters
+- the environment
+
+```javascript
+const config = {
+  state,
+  actions,
+  getters,
+  env,
+};
+const store = new Store(config);
+```
+
+### Actions
+
+Actions are used to coordinate state changes. It can be used for both synchronous
+and asynchronous logic.
+
+```js
+const actions = {
+  async login({ state }, info) {
+    state.loginState = "pending";
+    try {
+      const loginInfo = await doSomeRPC("/login/", info);
+      state.loginState = loginInfo;
+    } catch (e) {
+      state.loginState = "error";
+    }
+  },
+};
+```
+
+The first argument to an action method is an object with four keys:
+
+- `state`: the current state of the store content,
+- `dispatch`: a function that can be used to dispatch other actions,
+- `getters`: an object containing all getters defined in the store,
+- `env`: the current environment. This is useful sometimes, in particular if
+  an action needs to apply some side effects (such as performing an rpc), and
+  the `rpc` method is located in the environment.
+
+Actions are called with the `dispatch` method on the store, and can receive an
+arbitrary number of arguments.
+
+```js
+store.dispatch("login", someInfo);
+```
+
+Note that anything returned by an action will also be returned by the `dispatch`
+call.
+
+Also, it is important to be aware that we need to be careful with asynchronous
+logic. Each state change will potentially trigger a rerendering, so we need to
+make sure that we do not have a partially corrupted state. Here is an example that
+is likely not a good idea:
+
+```javascript
+const actions = {
+  async fetchSomeData({ state }, recordId) {
+    state.recordId = recordId;
+    const data = await doSomeRPC("/read/", recordId);
+    state.recordData = data;
+  },
+};
+```
+
+In the previous example, there is a period of time in which the state has a
+`recordId` which does not correspond to the `recordData`. It is more likely that
+we want an atomic update: updating the `recordId` at the same time as the `recordData`
+values:
+
+```javascript
+const actions = {
+  async fetchSomeData({ state }, recordId) {
+    const data = await doSomeRPC("/read/", recordId);
+    state.recordId = recordId;
+    state.recordData = data;
+  },
+};
+```
+
+### Getters
+
+Usually, data contained in the store will be stored in a normalized way. For
+example,
+
+```js
+{
+    posts: [{id: 11, authorId: 4, content: 'Greetings'}],
+    authors: [{id: 4, name: 'John'}]
+}
+```
+
+However, the user interface will probably need some denormalized data like
+
+```js
+{id: 11, author: {id: 4, name: 'John'}, content: 'Greetings'}
+```
+
+This is what `getters` are for: they give a centralized way to process and
+transform the data contained in the store.
+
+```js
+const getters = {
+  getPost({ state }, id) {
+    const post = state.posts.find((p) => p.id === id);
+    const author = state.authors.find((a) => a.id === post.id);
+    return {
+      id,
+      author,
+      content: post.content,
+    };
+  },
+};
+
+// somewhere else
+const post = store.getters.getPost(id);
+```
+
+Getters take _at most_ one argument.
+
+Note that getters are not cached.
+
+### Connecting a Component
+
+At some point, we need a way to interact with the store from a component. This
+means that the component needs a reference to the store. By default, it looks
+for it in the `env.store` key. However, this can be configured with the `useStore`
+hook.
+
+Every component-store interactions are done with the help of the three store hooks:
+
+- [`useStore`](#usestore) to subscribe a component to some part of the store state,
+- [`useDispatch`](#usedispatch) to get a reference to a dispatch function,
+- [`useGetters`](#usegetters) to get a reference to the getters defined in the store.
+
+Assume we have this store:
+
+```javascript
+const actions = {
+  increment({ state }, val) {
+    state.counter.value += val;
+  },
+};
+
+const state = {
+  counter: { value: 0 },
+};
+const store = new owl.Store({ state, actions });
+```
+
+To make it accessible to the complete application, we will put it in the
+environment:
+
+```js
+// in this example, the root component is App
+App.env.store = store;
+```
+
+A counter component can then select this value and dispatch an action like this:
+
+```js
+class Counter extends Component {
+  counter = useStore((state) => state.counter);
+  dispatch = useDispatch();
+}
+
+const counter = new Counter({ store, qweb });
+```
+
+```xml
+<button t-name="Counter" t-on-click="dispatch('increment')">
+  Click Me! [<t t-esc="counter.value"/>]
+</button>
+```
+
+### `useStore`
+
+The `useStore` hook is used to select some part of the store state. It accepts
+two arguments:
+
+- a selector function, which takes the store state as first argument (and the
+  component props as second argument) and which must return the part of the
+  store state that will be made available and observed for changes,
+- optionally, an object which can have the following optional keys:
+  - a `store` key containing a store object if we want to use another store than
+    the default store,
+  - an `isEqual` key containing an equality function if we want to specialize
+    the comparison (the function must accept two arguments: the previous result
+    and the new result, and must return whether they are equal),
+  - and an `onUpdate` key containing an update function if we want to execute an
+    arbitrary code every time the selected state changes (the function will
+    receive one argument, the new result, and can execute arbitrary code).
+
+If the `useStore` selector returns a sub part of the store state, the component
+will only be rerendered whenever this part of the state changes. Otherwise, it
+will perform a strict equality check (unless the `isEqual` option is defined,
+then it will call it) and will update the component every time this check fails.
+
+Note that if the selector function returns a primitive type, the result of
+`useStore` will be immutable and it will not react to changes. In this case, it
+is important to define the `onUpdate` option to properly update the value
+manually when it changes.
+
+Also, the return value from `useStore` is not supposed to be modified. The store
+state should only be updated with actions.
+
+### `useDispatch`
+
+The `useDispatch` hook is useful when a component needs to be able to dispatch
+actions. It takes an optional argument, which is a store. If not given, it will
+use the store in the environment.
+
+Note that a component does not need to be connected in any other way to the store.
+For example:
+
+```js
+class DoSomethingButton extends Component {
+  static template = xml`<button t-on-click="dispatch('something')">Click</button>`;
+  dispatch = useDispatch();
+}
+```
+
+### `useGetters`
+
+The `useGetters` hook is useful when a component needs to be able to use the
+getters defined in a store. It takes an optional argument, which is a store. If
+not given, it will use the store in the environment.
+
+Note that a component does not need to be connected in any other way to the store.
+For example:
+
+```js
+class InfoButton extends Component {
+  static template = xml`<span><t t-esc="getters.somevalue()"></span>`;
+  getters = useGetters();
+}
+```
+
+### Semantics
+
+The `Store` class and the `useStore` hook try to be smart and to optimize as much
+as possible the rendering and update process. What is important to know is:
+
+- components are always updated in the order of their creation (so, parent
+  before children),
+- they are updated only if they are in the DOM,
+- if a parent is asynchronous, the system will wait for it to complete its
+  update before updating other components,
+- in general, updates are not coordinated. This is not a problem for synchronous
+  components, but if there are many asynchronous components, this could lead to
+  a situation where some part of the UI is updated and some other part of the UI is
+  not updated.
+
+### Good Practices
+
+- avoid asynchronous components as much as possible. Asynchronous components
+  lead to situations where parts of the UI is not updated immediately,
+- do not be afraid to connect many components, parent or children if needed. For
+  example, a `MessageList` component could get a list of ids in its `useStore`
+  call and a `Message` component could get the data of its own
+  message,
+- since the `useStore` function is called for each connected component,
+  for each state update, it is important to make sure that these functions are
+  as fast as possible.

doc/reference/tags.md

@@ -0,0 +1,184 @@
+# 🦉 Tags 🦉
+
+## Content
+
+- [Overview](#overview)
+- [`xml` tag](#xml-tag)
+- [`css` tag](#css-tag)
+
+## Overview
+
+Tags are very small helpers intended to make it easy to write inline templates
+or styles. There are currently two tags: `css` and `xml`. With these functions,
+it is possible to write [single file components](../learning/how_to_write_sfc.md).
+
+## XML tag
+
+The `xml` tag is certainly the most useful tag. It is used to define an inline
+QWeb template for a component. Without tags, creating a standalone component
+would look like this:
+
+```js
+import { Component } from 'owl'
+
+const name = 'some-unique-name';
+const template = `
+    <div>
+        <span t-if="somecondition">text</span>
+        <button t-on-click="someMethod">Click</button>
+    </div>
+`;
+QWeb.registerTemplate(name, template);
+
+class MyComponent extends Component {
+    static template = name;
+
+    ...
+}
+```
+
+With tags, this process is slightly simplified. The name is uniquely generated,
+and the template is automatically registered:
+
+```js
+const { Component } = owl;
+const { xml } = owl.tags;
+
+class MyComponent extends Component {
+    static template = xml`
+        <div>
+            <span t-if="somecondition">text</span>
+            <button t-on-click="someMethod">Click</button>
+        </div>
+    `;
+
+    ...
+}
+```
+
+## CSS tag
+
+The CSS tag is useful to define a css stylesheet in the javascript file:
+
+```js
+class MyComponent extends Component {
+    static template = xml`
+        <div class="my-component">some template</div>
+    `;
+    static css`
+      .my-component {
+          color: red;
+      }
+    `;
+}
+```
+
+The `css` tag registers internally the css information. Then, whenever the first
+instance of the component is created, will add a `<style>` tag to the document
+`<head>`.
+
+Note that to make it more useful, like other css preprocessors, the `css` tag
+accepts a small extension of the css specification: css scopes can be nested,
+and the rules will then be expanded by the `css` helper:
+
+```scss
+.my-component {
+  display: block;
+  .sub-component h {
+    color: red;
+  }
+}
+```
+
+will be formatted as:
+
+```css
+.my-component {
+  display: block;
+}
+.my-component .sub-component h {
+  color: red;
+}
+```
+
+This extension brings another useful feature: the `&` selector which refers to
+the parent selector. For example, we want our component to be red when hovered.
+We would like to write something like:
+
+```scss
+.my-component {
+  display: block;
+  :hover {
+    color: red;
+  }
+}
+```
+
+but it will be formatted as:
+
+```css
+.my-component {
+  display: block;
+}
+.my-component :hover {
+  color: red;
+}
+```
+
+The `&` selector can be used to solve this problem:
+
+```scss
+.my-component {
+  display: block;
+  &:hover {
+    color: red;
+  }
+}
+```
+
+will be formatted as:
+
+```css
+.my-component {
+  display: block;
+}
+.my-component:hover {
+  color: red;
+}
+```
+
+Now, there is no additional processing done by the `css` tag. However, since it
+is done in javascript at runtime, we actually have more power. For example:
+
+1. sharing values between javascript and css:
+
+```js
+import { theme } from "./theme";
+
+class MyComponent extends Component {
+  static template = xml`<div class="my-component">...</div>`;
+  static style = css`
+    .my-component {
+      color: ${theme.MAIN_COLOR};
+      background-color: ${theme.SECONDARY_color};
+    }
+  `;
+}
+```
+
+2. scoping rules to the current component:
+
+```js
+import { generateUUID } from "./utils";
+
+const uuid = generateUUID();
+
+class MyComponent extends Component {
+  static template = xml`<div data-o-${uuid}="">...</div>`;
+  static style = css`
+    [data-o-${uuid}] {
+      color: red;
+    }
+  `;
+}
+```

doc/reference/utils.md

@@ -0,0 +1,148 @@
+# 🦉 Utils 🦉
+
+Owl export a few useful utility functions, to help with common issues. Those
+functions are all available in the `owl.utils` namespace.
+
+## Content
+
+- [`whenReady`](#whenready): executing code when DOM is ready
+- [`loadJS`](#loadjs): loading script files
+- [`loadFile`](#loadfile): loading a file (useful for templates)
+- [`escape`](#escape): sanitizing strings
+- [`debounce`](#debounce): limiting rate of function calls
+- [`shallowEqual`](#shallowequal): shallow object comparison
+
+## `whenReady`
+
+The function `whenReady` returns a `Promise` resolved when the DOM is ready (if
+not ready yet, resolved directly otherwise). If called with a callback as
+argument, it executes it as soon as the DOM ready (or directly).
+
+```js
+Promise.all([loadFile("templates.xml"), owl.utils.whenReady()]).then(function ([templates]) {
+  const qweb = new owl.QWeb({ templates });
+  const app = new App({ qweb });
+  app.mount(document.body);
+});
+```
+
+or alternatively:
+
+```js
+owl.utils.whenReady(function () {
+  const qweb = new owl.QWeb();
+  const app = new App({ qweb });
+  app.mount(document.body);
+});
+```
+
+## `loadJS`
+
+`loadJS` takes a url (string) for a javascript resource, and loads it (by adding
+a script tag in the document head). It returns a promise, so the caller can
+properly reacts when it is ready. Also, it is smart: it maintains a list of urls
+previously loaded (or currently being loaded), and prevent doing twice the work.
+
+For example, it is useful for lazy loading external libraries:
+
+```js
+class MyComponent extends owl.Component {
+  willStart() {
+    return owl.utils.loadJS("/static/libs/someLib.js");
+  }
+}
+```
+
+## `loadFile`
+
+`loadFile` is a helper function to fetch a file. It simply
+performs a `GET` request and returns the resulting string in a promise. The
+initial usecase for this function is to load a template file. For example:
+
+```js
+async function makeEnv() {
+  const templates = await owl.utils.loadFile("templates.xml");
+  const qweb = new owl.QWeb({ templates });
+  return { qweb };
+}
+```
+
+Note that unlike `loadJS`, this function returns the content of the file as a
+string. It does not add a `script` tag or any other side effect.
+
+## `escape`
+
+Sometimes, we need to display dynamic data (for example user-generated data) in
+the user interface. If this is done by a `QWeb` template, it is not an issue:
+
+```xml
+    <div><t t-esc="user.data"/></div>
+```
+
+The `QWeb` engine will create a `div` node and add the content of the `user.data`
+string as a text node, so the web browser will not parse it as html. However,
+it may be a problem if this is done with some javascript code like this:
+
+```js
+class BadComponent extends Component {
+  // some template with a ref to a div
+  // some code ...
+
+  mounted() {
+    this.divRef.el.innerHTML = this.state.value;
+  }
+}
+```
+
+In this case, the content of the `div` will be parsed as html, which may inject
+unwanted behaviour. To fix this, the `escape` function will simply transform a
+string into an escaped version of the same string, which will be properly displayed
+by the browser, but which will not be parsed as html (for example, `"<ok>"` is
+escaped to the string: `"&lt;ok&gt;"`). So, the bad example above can be fixed
+with the following change:
+
+```js
+this.divRef.el.innerHTML = owl.utils.escape(this.state.value);
+```
+
+## `debounce`
+
+The `debounce` function is useful when we want to limit the number of times some
+function/action is perfomed. For example, this may be useful to prevent issue
+with people double clicking on a button.
+
+It takes three arguments:
+
+- `func` (function): this is the function that will be rate limited
+- `wait` (number): this is the number of milliseconds that we want to use to
+  rate limit the function `func`
+- `immediate` (optional, boolean, default=false): if `immediate` is true, the
+  function will be triggered immediately (leading edge of the interval). If false,
+  the function will be triggered at the end (trailing edge).
+
+It returns a function. For example:
+
+```js
+const debounce = owl.utils.debounce;
+window.addEventListener("mousemove", debounce(doSomething, 100));
+```
+
+As this example shows, it is usualy useful for event handlers which are triggered
+very quickly, such as `scroll` or `mousemove` events.
+
+## `shallowEqual`
+
+This function checks if two objects have the same values assigned to each keys:
+
+```js
+shallowEqual({ a: 1, b: 2 }, { a: 1, b: 2 }); // true
+shallowEqual({ a: 1, b: 2 }, { a: 1, b: 3 }); // false
+```
+
+However, for performance reasons, it assumes that the two objects have the same
+keys. If we are in a situation where this is not guaranteed, the following code
+will work:
+
+```js
+const completeShallowEqual = (a, b) => shallowEqual(a, b) && shallowEqual(b, a);
+```

doc/store.md

@@ -1,149 +0,0 @@
-# 🦉 Store 🦉
-
-## Content
-
-- [Overview](#overview)
-- [Example](#example)
-- [Reference](#reference)
-  - [Public API](#public-api)
-  - [Mutations](#mutations)
-  - [Actions](#actions)
-  - [Getters](#getters)
-  - [Connecting a component](#connecting-a-component)
-
-## Overview
-
-Managing the state in an application is not an easy task. In some cases, the
-state of an application can be part of the component tree, in a natural way.
-However, there are situations where some part of the state need to be displayed
-in various parts of the user interface, and then, it is not obvious which
-component should own which part of the state.
-
-Owl's solution to this issue is a centralized store. It is a class that owns
-some state, and let the developer update it in a structured way (through
-mutations and actions). Owl components can then connect to the store, and will
-be updated if necessary.
-
-Note: Owl's store is inspired by React Redux and VueX.
-
-## Example
-
-Here is what a simple store look like:
-
-```js
-const actions = {
-    addTodo({commit}, message) {
-        commit('addTodo', message);
-    }
-};
-
-const mutations = {
-    addTodo({state}, message) {
-        const todo = {
-            id: state.nextId++,
-            message,
-            isCompleted: false,
-        };
-        state.todos.push(todo);
-    },
-};
-
-const state = {
-    todos: [],
-    nextId: 1,
-};
-
-const store = new owl.Store({state, actions, mutations});
-store.on('update', () => console.log(store.state));
-
-// updating the state
-store.dispatch('addTodo', 'fix all bugs');
-```
-
-
-## Reference
-
-The store is a simple `owl.EventBus` that triggers `update` events whenever its
-state is changed.  Note that these events are triggered only after a microtask
-tick, so only one event will be triggered for any number of state changes in a
-call stack.
-
-Also, it is important to mention that the state is observed (with a `owl.Observer`),
-which is the reason why it is able to know if it was changed.  This implies that
-state changes need to be done carefully in some cases (adding a new key to an
-object, or modifying an array with the `arr[i] = newValue` syntax).  See the
-[Observer](observer.md)'s documentation for more details.
-
-### Public API
-
-1. `constructor`
-2. `commit`
-3. `dispatch`
-
-### Mutations
-
-Mutations are the only way to modify the state.  Changing the state outside a
-mutation is not allowed (and should throw an error).  Mutations are synchronous.
-
-### Actions
-
-Actions are used to coordinate state changes.  It is also useful whenever some
-asynchronous logic is necessary.  For example, fetching data should be done
-in an action.
-
-```js
-const actions = {
-    async login({commit}) {
-        commit('setLoginState', 'pending');
-        try {
-            const loginInfo = await doSomeRPC('/login/', 'someinfo');
-            commit('setLoginState', loginInfo);
-        } catch {
-            commit('setLoginState', 'error');
-        }
-    }
-};
-```
-
-### Getters
-
-Usually, data contained in the store will be stored in a normalized way. For
-example,
-
-```js
-{
-    posts: [{id: 11, authorId: 4, content: 'Greetings'}],
-    authors: [{id: 4, name: 'John'}]
-}
-```
-
-However, the user interface will probably need some denormalized data like
-
-```js
-{id: 11, author: {id: 4, name: 'John'}, content: 'Greetings'}
-```
-
-This is what `getters` are for: they give a centralized way to process and
-transform the data contained in the store.
-
-```js
-const getters = {
-    getPost({state}, id) {
-        const post = state.posts.find(p => p.id === id);
-        const author = state.authors.find(a => a.id = post.id);
-        return {
-            id,
-            author,
-            content: post.content
-        };
-    },
-};
-
-// somewhere else
-const post = store.getters.getPost(id);
-
-```
-
-### Connecting a component
-
-Todo

doc/utils.md

@@ -1,41 +0,0 @@
-# 🦉 Utils 🦉
-
-Owl export a few useful utility functions, to help with common issues. Those
-functions are all available in the `owl.utils` namespace.
-
-## Content
-
-- [`whenReady`](#whenready)
-- [`loadJS`](#loadjs)
-- [`loadTemplates`](#loadtemplates)
-- [`escape`](#escape)
-- [`debounce`](#debounce)
-- [`patch` and `unpatch`](#patchandunpatch)
-
-## `whenReady`
-
-The function `whenReady` is useful to register some code that need to be executed
-as soon as the document (page) is ready:
-
-```js
-owl.utils.whenReady(function () {
-    const qweb = new owl.QWeb();
-    const app = new App({ qweb });
-    app.mount(document.body);
-});
-```
-
-## `loadJS`
-
-## `loadTemplates`
-
-## `escape`
-
-## `debounce`
-
-## `patch` and `unpatch`
-
-
-
-
-

doc/vdom.md

@@ -1,3 +0,0 @@
-# 🦉 VDom 🦉
-
-Owl's virtual dom is a fork of [snabbdom](https://github.com/snabbdom/snabbdom).

extras/benchmarks/odoo-widgets-12.0/templates.xml

@@ -1,30 +0,0 @@
-<templates>
-    <div class="main" t-name="root">
-        <div class="left-thing">
-            <div class="message_count">
-                Number of msg: 0
-            </div>
-            <button class="o_btn_msg 100">Add 100 messages</button>
-            <button class="o_btn_msg 1000">Add 1000 messages</button>
-            <button class="o_btn_msg 10000">Add 10000 messages</button>
-            <button class="o_btn_msg 50000">Add 50000 messages</button>
-            <button class="updateSomeMessages">Update every 10th message</button>
-            <button class="clear">Clear</button>
-        </div>
-        <div class="right-thing">
-            <div class="content">
-            </div>
-        </div>
-    </div>
-
-    <div t-name="message" class="message">
-        <span class="author"><t t-esc="widget.author"/></span>
-        <span class="msg"><t t-esc="widget.msg"/></span>
-        <button class="remove" >Remove</button>
-    </div>
-
-  <div t-name="counter">
-    <button class="o_increment"></button>
-  </div>
-
-</templates>

extras/benchmarks/odoo-widgets-12.3/templates.xml

@@ -1,30 +0,0 @@
-<templates>
-    <div class="main" t-name="root">
-        <div class="left-thing">
-            <div class="message_count">
-                Number of msg: 0
-            </div>
-            <button class="o_btn_msg 100">Add 100 messages</button>
-            <button class="o_btn_msg 1000">Add 1000 messages</button>
-            <button class="o_btn_msg 10000">Add 10000 messages</button>
-            <button class="o_btn_msg 50000">Add 50000 messages</button>
-            <button class="updateSomeMessages">Update every 10th message</button>
-            <button class="clear">Clear</button>
-        </div>
-        <div class="right-thing">
-            <div class="content">
-            </div>
-        </div>
-    </div>
-
-    <div t-name="message" class="message">
-        <span class="author"><t t-esc="widget.author"/></span>
-        <span class="msg"><t t-esc="widget.msg"/></span>
-        <button class="remove" >Remove</button>
-    </div>
-
-  <div t-name="counter">
-    <button class="o_increment"></button>
-  </div>
-
-</templates>

extras/benchmarks/owl-0.10.0/app.js

@@ -1,84 +0,0 @@
-import { buildData, startMeasure, stopMeasure } from "../shared/utils.js";
-
-//------------------------------------------------------------------------------
-// Likes Counter Widget
-//------------------------------------------------------------------------------
-class Counter extends owl.Component {
-  template = "counter";
-  state = { counter: 0 };
-
-  increment() {
-    this.state.counter++;
-  }
-}
-
-//------------------------------------------------------------------------------
-// Message Widget
-//------------------------------------------------------------------------------
-class Message extends owl.Component {
-  template = "message";
-  widgets = { Counter };
-
-  shouldUpdate(nextProps) {
-    return nextProps !== this.props;
-  }
-  removeMessage() {
-    this.trigger("remove_message", {
-      id: this.props.id
-    });
-  }
-}
-
-//------------------------------------------------------------------------------
-// Root Widget
-//------------------------------------------------------------------------------
-class App extends owl.Component {
-  template = "root";
-  widgets = { Message };
-  state = { messages: [] };
-
-  addMessages(n) {
-    startMeasure("add " + n);
-    const newMessages = buildData(n);
-    this.state.messages.push.apply(this.state.messages, newMessages);
-    stopMeasure();
-  }
-
-  clear() {
-    startMeasure("clear");
-    this.state.messages = [];
-    stopMeasure();
-  }
-
-  updateSomeMessages() {
-    startMeasure("update every 10th");
-    const messages = this.state.messages;
-    for (let i = 0; i < this.state.messages.length; i += 10) {
-      const msg = Object.assign({}, messages[i]);
-      msg.author += '!!!';
-      this.set(messages, i, msg);
-    }
-    stopMeasure();
-  }
-
-  removeMessage(data) {
-    startMeasure("remove message");
-    const index = this.state.messages.findIndex(m => m.id === data.id);
-    this.state.messages.splice(index, 1);
-    stopMeasure();
-  }
-}
-
-//------------------------------------------------------------------------------
-// Application initialization
-//------------------------------------------------------------------------------
-async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
-  const env = {
-    qweb: new owl.QWeb(templates)
-  };
-  const app = new App(env);
-  app.mount(document.body);
-}
-
-start();

extras/benchmarks/owl-0.10.0/templates.xml

@@ -1,32 +0,0 @@
-<templates>
-  <div t-name="root" class="main">
-      <div class="left-thing">
-          <div>Number of msg: <t t-esc="state.messages.length"/></div>
-          <button t-on-click="addMessages(100)">Add 100 messages</button>
-          <button t-on-click="addMessages(1000)">Add 1000 messages</button>
-          <button t-on-click="addMessages(10000)">Add 10000 messages</button>
-          <button t-on-click="addMessages(50000)">Add 50000 messages</button>
-          <button t-on-click="updateSomeMessages">Update every 10th message</button>
-          <button t-on-click="clear">Clear</button>
-      </div>
-      <div class="right-thing">
-          <div class="content">
-              <t t-foreach="state.messages" t-as="message">
-                  <t t-widget="Message" t-key="message.id" t-props="message" t-on-remove_message="removeMessage"/>
-              </t>
-          </div>
-      </div>
-  </div>
-
-  <div t-name="message" class="message">
-    <span class="author"><t t-esc="props.author"/></span>
-    <span class="msg"><t t-esc="props.msg"/></span>
-    <button class="remove" t-on-click="removeMessage">Remove</button>
-    <t t-widget="Counter"/>
-  </div>
-
-  <div t-name="counter">
-    <button t-on-click="increment">Value: <t t-esc="state.counter"/></button>
-  </div>
-
-</templates>

extras/benchmarks/owl-0.7.0/app.js

@@ -1,85 +0,0 @@
-import { buildData, startMeasure, stopMeasure } from "../shared/utils.js";
-
-//------------------------------------------------------------------------------
-// Likes Counter Widget
-//------------------------------------------------------------------------------
-class Counter extends owl.Component {
-  template = "counter";
-  state = { counter: 0 };
-
-  increment() {
-    this.state.counter++;
-  }
-}
-
-//------------------------------------------------------------------------------
-// Message Widget
-//------------------------------------------------------------------------------
-class Message extends owl.Component {
-  template = "message";
-  widgets = { Counter };
-
-  shouldUpdate(nextProps) {
-    return nextProps !== this.props;
-  }
-
-  removeMessage() {
-    this.trigger("remove_message", {
-      id: this.props.id
-    });
-  }
-}
-
-//------------------------------------------------------------------------------
-// Root Widget
-//------------------------------------------------------------------------------
-class App extends owl.Component {
-  template = "root";
-  widgets = { Message };
-  state = { messages: [] };
-
-  addMessages(n) {
-    startMeasure("add " + n);
-    const newMessages = buildData(n);
-    this.state.messages.push.apply(this.state.messages, newMessages);
-    stopMeasure();
-  }
-
-  clear() {
-    startMeasure("clear");
-    this.state.messages = [];
-    stopMeasure();
-  }
-
-  updateSomeMessages() {
-    startMeasure("update every 10th");
-    const messages = this.state.messages;
-    for (let i = 0; i < this.state.messages.length; i += 10) {
-      const msg = Object.assign({}, messages[i]);
-      msg.author += '!!!';
-      this.set(messages, i, msg);
-    }
-    stopMeasure();
-  }
-
-  removeMessage(data) {
-    startMeasure('remove message');
-    const index = this.state.messages.findIndex(m => m.id === data.id);
-    this.state.messages.splice(index, 1);
-    stopMeasure();
-  }
-}
-
-//------------------------------------------------------------------------------
-// Application initialization
-//------------------------------------------------------------------------------
-async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
-  const env = {
-    qweb: new owl.QWeb(templates)
-  };
-  const app = new App(env);
-  app.mount(document.body);
-}
-
-start();

extras/benchmarks/owl-0.7.0/templates.xml

@@ -1,32 +0,0 @@
-<templates>
-  <div t-name="root" class="main">
-      <div class="left-thing">
-          <div>Number of msg: <t t-esc="state.messages.length"/></div>
-          <button t-on-click="addMessages(100)">Add 100 messages</button>
-          <button t-on-click="addMessages(1000)">Add 1000 messages</button>
-          <button t-on-click="addMessages(10000)">Add 10000 messages</button>
-          <button t-on-click="addMessages(50000)">Add 50000 messages</button>
-          <button t-on-click="updateSomeMessages">Update every 10th message</button>
-          <button t-on-click="clear">Clear</button>
-      </div>
-      <div class="right-thing">
-          <div class="content">
-              <t t-foreach="state.messages" t-as="message">
-                  <t t-widget="Message" t-key="message.id" t-props="message" t-on-remove_message="removeMessage"/>
-              </t>
-          </div>
-      </div>
-  </div>
-
-  <div t-name="message" class="message">
-    <span class="author"><t t-esc="props.author"/></span>
-    <span class="msg"><t t-esc="props.msg"/></span>
-    <button class="remove" t-on-click="removeMessage">Remove</button>
-    <t t-widget="Counter"/>
-  </div>
-
-  <div t-name="counter">
-    <button t-on-click="increment">Value: <t t-esc="state.counter"/></button>
-  </div>
-
-</templates>

extras/benchmarks/owl-0.8.0/app.js

@@ -1,84 +0,0 @@
-import { buildData, startMeasure, stopMeasure } from "../shared/utils.js";
-
-//------------------------------------------------------------------------------
-// Likes Counter Widget
-//------------------------------------------------------------------------------
-class Counter extends owl.Component {
-  template = "counter";
-  state = { counter: 0 };
-
-  increment() {
-    this.state.counter++;
-  }
-}
-
-//------------------------------------------------------------------------------
-// Message Widget
-//------------------------------------------------------------------------------
-class Message extends owl.Component {
-  template = "message";
-  widgets = { Counter };
-
-  shouldUpdate(nextProps) {
-    return nextProps !== this.props;
-  }
-  removeMessage() {
-    this.trigger("remove_message", {
-      id: this.props.id
-    });
-  }
-}
-
-//------------------------------------------------------------------------------
-// Root Widget
-//------------------------------------------------------------------------------
-class App extends owl.Component {
-  template = "root";
-  widgets = { Message };
-  state = { messages: [] };
-
-  addMessages(n) {
-    startMeasure("add " + n);
-    const newMessages = buildData(n);
-    this.state.messages.push.apply(this.state.messages, newMessages);
-    stopMeasure();
-  }
-
-  clear() {
-    startMeasure("clear");
-    this.state.messages = [];
-    stopMeasure();
-  }
-
-  updateSomeMessages() {
-    startMeasure("update every 10th");
-    const messages = this.state.messages;
-    for (let i = 0; i < this.state.messages.length; i += 10) {
-      const msg = Object.assign({}, messages[i]);
-      msg.author += '!!!';
-      this.set(messages, i, msg);
-    }
-    stopMeasure();
-  }
-
-  removeMessage(data) {
-    startMeasure("remove message");
-    const index = this.state.messages.findIndex(m => m.id === data.id);
-    this.state.messages.splice(index, 1);
-    stopMeasure();
-  }
-}
-
-//------------------------------------------------------------------------------
-// Application initialization
-//------------------------------------------------------------------------------
-async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
-  const env = {
-    qweb: new owl.QWeb(templates)
-  };
-  const app = new App(env);
-  app.mount(document.body);
-}
-
-start();

extras/benchmarks/owl-0.8.0/templates.xml

@@ -1,32 +0,0 @@
-<templates>
-  <div t-name="root" class="main">
-      <div class="left-thing">
-          <div>Number of msg: <t t-esc="state.messages.length"/></div>
-          <button t-on-click="addMessages(100)">Add 100 messages</button>
-          <button t-on-click="addMessages(1000)">Add 1000 messages</button>
-          <button t-on-click="addMessages(10000)">Add 10000 messages</button>
-          <button t-on-click="addMessages(50000)">Add 50000 messages</button>
-          <button t-on-click="updateSomeMessages">Update every 10th message</button>
-          <button t-on-click="clear">Clear</button>
-      </div>
-      <div class="right-thing">
-          <div class="content">
-              <t t-foreach="state.messages" t-as="message">
-                  <t t-widget="Message" t-key="message.id" t-props="message" t-on-remove_message="removeMessage"/>
-              </t>
-          </div>
-      </div>
-  </div>
-
-  <div t-name="message" class="message">
-    <span class="author"><t t-esc="props.author"/></span>
-    <span class="msg"><t t-esc="props.msg"/></span>
-    <button class="remove" t-on-click="removeMessage">Remove</button>
-    <t t-widget="Counter"/>
-  </div>
-
-  <div t-name="counter">
-    <button t-on-click="increment">Value: <t t-esc="state.counter"/></button>
-  </div>
-
-</templates>

extras/benchmarks/owl-0.9.0/app.js

@@ -1,84 +0,0 @@
-import { buildData, startMeasure, stopMeasure } from "../shared/utils.js";
-
-//------------------------------------------------------------------------------
-// Likes Counter Widget
-//------------------------------------------------------------------------------
-class Counter extends owl.Component {
-  template = "counter";
-  state = { counter: 0 };
-
-  increment() {
-    this.state.counter++;
-  }
-}
-
-//------------------------------------------------------------------------------
-// Message Widget
-//------------------------------------------------------------------------------
-class Message extends owl.Component {
-  template = "message";
-  widgets = { Counter };
-
-  shouldUpdate(nextProps) {
-    return nextProps !== this.props;
-  }
-  removeMessage() {
-    this.trigger("remove_message", {
-      id: this.props.id
-    });
-  }
-}
-
-//------------------------------------------------------------------------------
-// Root Widget
-//------------------------------------------------------------------------------
-class App extends owl.Component {
-  template = "root";
-  widgets = { Message };
-  state = { messages: [] };
-
-  addMessages(n) {
-    startMeasure("add " + n);
-    const newMessages = buildData(n);
-    this.state.messages.push.apply(this.state.messages, newMessages);
-    stopMeasure();
-  }
-
-  clear() {
-    startMeasure("clear");
-    this.state.messages = [];
-    stopMeasure();
-  }
-
-  updateSomeMessages() {
-    startMeasure("update every 10th");
-    const messages = this.state.messages;
-    for (let i = 0; i < this.state.messages.length; i += 10) {
-      const msg = Object.assign({}, messages[i]);
-      msg.author += '!!!';
-      this.set(messages, i, msg);
-    }
-    stopMeasure();
-  }
-
-  removeMessage(data) {
-    startMeasure("remove message");
-    const index = this.state.messages.findIndex(m => m.id === data.id);
-    this.state.messages.splice(index, 1);
-    stopMeasure();
-  }
-}
-
-//------------------------------------------------------------------------------
-// Application initialization
-//------------------------------------------------------------------------------
-async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
-  const env = {
-    qweb: new owl.QWeb(templates)
-  };
-  const app = new App(env);
-  app.mount(document.body);
-}
-
-start();

extras/benchmarks/owl-0.9.0/templates.xml

@@ -1,32 +0,0 @@
-<templates>
-  <div t-name="root" class="main">
-      <div class="left-thing">
-          <div>Number of msg: <t t-esc="state.messages.length"/></div>
-          <button t-on-click="addMessages(100)">Add 100 messages</button>
-          <button t-on-click="addMessages(1000)">Add 1000 messages</button>
-          <button t-on-click="addMessages(10000)">Add 10000 messages</button>
-          <button t-on-click="addMessages(50000)">Add 50000 messages</button>
-          <button t-on-click="updateSomeMessages">Update every 10th message</button>
-          <button t-on-click="clear">Clear</button>
-      </div>
-      <div class="right-thing">
-          <div class="content">
-              <t t-foreach="state.messages" t-as="message">
-                  <t t-widget="Message" t-key="message.id" t-props="message" t-on-remove_message="removeMessage"/>
-              </t>
-          </div>
-      </div>
-  </div>
-
-  <div t-name="message" class="message">
-    <span class="author"><t t-esc="props.author"/></span>
-    <span class="msg"><t t-esc="props.msg"/></span>
-    <button class="remove" t-on-click="removeMessage">Remove</button>
-    <t t-widget="Counter"/>
-  </div>
-
-  <div t-name="counter">
-    <button t-on-click="increment">Value: <t t-esc="state.counter"/></button>
-  </div>
-
-</templates>

extras/benchmarks/owl-master/app.js

@@ -1,81 +0,0 @@
-import { buildData, startMeasure, stopMeasure } from "../shared/utils.js";
-
-//------------------------------------------------------------------------------
-// Likes Counter Widget
-//------------------------------------------------------------------------------
-class Counter extends owl.Component {
-  state = { counter: 0 };
-
-  increment() {
-    this.state.counter++;
-  }
-}
-
-//------------------------------------------------------------------------------
-// Message Widget
-//------------------------------------------------------------------------------
-class Message extends owl.Component {
-  widgets = { Counter };
-
-  shouldUpdate(nextProps) {
-    return nextProps !== this.props;
-  }
-  removeMessage() {
-    this.trigger("remove_message", {
-      id: this.props.id
-    });
-  }
-}
-
-//------------------------------------------------------------------------------
-// Root Widget
-//------------------------------------------------------------------------------
-class App extends owl.Component {
-  widgets = { Message };
-  state = { messages: [] };
-
-  addMessages(n) {
-    startMeasure("add " + n);
-    const newMessages = buildData(n);
-    this.state.messages.push.apply(this.state.messages, newMessages);
-    stopMeasure();
-  }
-
-  clear() {
-    startMeasure("clear");
-    this.state.messages = [];
-    stopMeasure();
-  }
-
-  updateSomeMessages() {
-    startMeasure("update every 10th");
-    const messages = this.state.messages;
-    for (let i = 0; i < this.state.messages.length; i += 10) {
-      const msg = Object.assign({}, messages[i]);
-      msg.author += '!!!';
-      this.set(messages, i, msg);
-    }
-    stopMeasure();
-  }
-
-  removeMessage(data) {
-    startMeasure("remove message");
-    const index = this.state.messages.findIndex(m => m.id === data.id);
-    this.state.messages.splice(index, 1);
-    stopMeasure();
-  }
-}
-
-//------------------------------------------------------------------------------
-// Application initialization
-//------------------------------------------------------------------------------
-async function start() {
-  const templates = await owl.utils.loadTemplates("templates.xml");
-  const env = {
-    qweb: new owl.QWeb(templates)
-  };
-  const app = new App(env);
-  app.mount(document.body);
-}
-
-start();

extras/benchmarks/owl-master/templates.xml

@@ -1,32 +0,0 @@
-<templates>
-  <div t-name="App" class="main">
-      <div class="left-thing">
-          <div>Number of msg: <t t-esc="state.messages.length"/></div>
-          <button t-on-click="addMessages(100)">Add 100 messages</button>
-          <button t-on-click="addMessages(1000)">Add 1000 messages</button>
-          <button t-on-click="addMessages(10000)">Add 10000 messages</button>
-          <button t-on-click="addMessages(50000)">Add 50000 messages</button>
-          <button t-on-click="updateSomeMessages">Update every 10th message</button>
-          <button t-on-click="clear">Clear</button>
-      </div>
-      <div class="right-thing">
-          <div class="content">
-              <t t-foreach="state.messages" t-as="message">
-                  <t t-widget="Message" t-key="message.id" t-props="message" t-on-remove_message="removeMessage"/>
-              </t>
-          </div>
-      </div>
-  </div>
-
-  <div t-name="Message" class="message">
-    <span class="author"><t t-esc="props.author"/></span>
-    <span class="msg"><t t-esc="props.msg"/></span>
-    <button class="remove" t-on-click="removeMessage">Remove</button>
-    <t t-widget="Counter"/>
-  </div>
-
-  <div t-name="Counter">
-    <button t-on-click="increment">Value: <t t-esc="state.counter"/></button>
-  </div>
-
-</templates>

extras/benchmarks/react/app.js

@@ -1,221 +0,0 @@
-import { buildData, startMeasure, stopMeasure } from "../shared/utils.js";
-
-//------------------------------------------------------------------------------
-// Counter Widget
-//------------------------------------------------------------------------------
-class Counter extends React.Component {
-  constructor(props) {
-    super(props);
-    this.state = {
-      counter: 0
-    };
-    this.increment = this.increment.bind(this);
-  }
-
-  render() {
-    return React.createElement(
-      "div",
-      null,
-      React.createElement(
-        "button",
-        {
-          onClick: this.increment
-        },
-        "Value: ",
-        this.state.counter
-      )
-    );
-  }
-
-  increment() {
-    this.setState({
-      counter: this.state.counter + 1
-    });
-  }
-}
-//------------------------------------------------------------------------------
-// Message Widget
-//------------------------------------------------------------------------------
-class Message extends React.Component {
-  constructor(props) {
-    super(props);
-    this.removeMessage = this.removeMessage.bind(this);
-  }
-
-  render() {
-    return React.createElement(
-      "div",
-      {
-        className: "message"
-      },
-      React.createElement(
-        "span",
-        {
-          className: "author"
-        },
-        this.props.message.author
-      ),
-      React.createElement(
-        "span",
-        {
-          className: "msg"
-        },
-        this.props.message.msg
-      ),
-      React.createElement(
-        "button",
-        {
-          className: "remove",
-          onClick: this.removeMessage
-        },
-        "Remove"
-      ),
-      React.createElement(Counter, null)
-    );
-  }
-
-  removeMessage() {
-    this.props.removeCB(this.props.message.id);
-  }
-}
-
-//------------------------------------------------------------------------------
-// Root Widget
-//------------------------------------------------------------------------------
-class Main extends React.Component {
-  constructor(props) {
-    super(props);
-    this.state = {
-      messages: []
-    };
-    this.removeMessage = this.removeMessage.bind(this);
-  }
-
-  render() {
-    const msgList = this.state.messages.map(m =>
-      React.createElement(Message, {
-        key: m.id,
-        message: m,
-        removeCB: this.removeMessage
-      })
-    );
-    return React.createElement(
-      "div",
-      {
-        className: "main"
-      },
-      React.createElement(
-        "div",
-        {
-          className: "left-thing"
-        },
-        React.createElement(
-          "div",
-          null,
-          "Number of msg: ",
-          this.state.messages.length
-        ),
-        React.createElement(
-          "button",
-          {
-            onClick: _ => this.addMessages(100)
-          },
-          "Add 100 messages"
-        ),
-        React.createElement(
-          "button",
-          {
-            onClick: _ => this.addMessages(1000)
-          },
-          "Add 1000 messages"
-        ),
-        React.createElement(
-          "button",
-          {
-            onClick: _ => this.addMessages(10000)
-          },
-          "Add 10000 messages"
-        ),
-        React.createElement(
-          "button",
-          {
-            onClick: _ => this.addMessages(50000)
-          },
-          "Add 50000 messages"
-        ),
-        React.createElement(
-          "button",
-          {
-            onClick: _ => this.updateSomeMessages()
-          },
-          "Update every 10th messags"
-        ),
-        React.createElement(
-          "button",
-          {
-            onClick: _ => this.clear()
-          },
-          "Clear"
-        )
-      ),
-      React.createElement(
-        "div",
-        {
-          className: "right-thing"
-        },
-        React.createElement(
-          "div",
-          {
-            className: "content"
-          },
-          msgList
-        )
-      )
-    );
-  }
-
-  addMessages(n) {
-    startMeasure("add " + n);
-    const newMessages = this.state.messages.concat(buildData(n));
-    this.setState({
-      messages: newMessages
-    });
-    stopMeasure();
-  }
-
-  clear() {
-    startMeasure("clear");
-    this.setState({
-      messages: []
-    });
-    stopMeasure();
-  }
-
-  updateSomeMessages() {
-    startMeasure("update every 10th");
-    const messages = this.state.messages;
-    for (let i = 0; i < messages.length; i += 10) {
-      messages[i].author += "!!!";
-    }
-    this.forceUpdate();
-    stopMeasure();
-  }
-
-  removeMessage(id) {
-    startMeasure("remove message");
-    const index = this.state.messages.findIndex(m => m.id === id);
-    const messages = this.state.messages.slice();
-    messages.splice(index, 1);
-    this.setState({
-      messages
-    });
-    stopMeasure();
-  }
-} //-----------------------------
-// INIT
-//-----------------------------
-
-ReactDOM.render(
-  React.createElement(Main, null),
-  document.getElementById("main")
-);

extras/benchmarks/shared/main.css

@@ -1,42 +0,0 @@
-.main {
-  position: absolute;
-  left: 0;
-  right: 0;
-  top: 0;
-  bottom: 0;
-
-  display: grid;
-  grid-template-columns: 220px 1fr;
-}
-
-.left-thing {
-  background-color: gray;
-  padding: 20px;
-  color: white;
-}
-
-.left-thing button {
-  width: 100%;
-}
-
-.right-thing {
-  padding: 20px;
-  overflow: auto;
-}
-
-/* Message widget */
-.message .author {
-  font-weight: bold;
-}
-
-.message {
-  width: 400px;
-  background-color: lightblue;
-  margin: 10px 5px;
-  border-radius: 5px;
-  padding: 5px;
-}
-
-.remove {
-  float: right;
-}

extras/benchmarks/vue/app.js

@@ -1,106 +0,0 @@
-import { buildData, startMeasure, stopMeasure } from "../shared/utils.js";
-
-//------------------------------------------------------------------------------
-// Counter Widget
-//------------------------------------------------------------------------------
-Vue.component("likes-counter", {
-  data: function() {
-    return {
-      counter: 0
-    };
-  },
-  methods: {
-    increment() {
-      this.counter++;
-    }
-  },
-  template: `
-    <div>
-      <button @click="increment">Value: {{counter}}</button>
-    </div>`
-});
-
-//------------------------------------------------------------------------------
-// Message Widget
-//------------------------------------------------------------------------------
-Vue.component("my-message", {
-  props: ["msg"],
-  methods: {
-    removeMessage() {
-      this.$emit("removeMessage", this.msg.id);
-    }
-  },
-  template: `
-    <div class="message">
-        <span class="author">{{msg.author}}</span>
-        <span class="msg">{{msg.msg}}</span>
-        <button class="remove" @click="removeMessage">Remove</button>
-        <likes-counter></likes-counter>
-    </div>`
-});
-
-//------------------------------------------------------------------------------
-// Root Widget
-//------------------------------------------------------------------------------
-const App = {
-  name: "App",
-  data() {
-    return { messages: [] };
-  },
-  methods: {
-    addMessages(n) {
-      startMeasure("add " + n);
-      const newMessages = buildData(n);
-      this.messages.push.apply(this.messages, newMessages);
-      stopMeasure();
-    },
-
-    clear() {
-      startMeasure("clear");
-      this.messages = [];
-      stopMeasure();
-    },
-
-    updateSomeMessages() {
-      startMeasure("update every 10th");
-      const messages = this.messages;
-      for (let i = 0; i < this.messages.length; i += 10) {
-        messages[i].author += "!!!";
-      }
-      stopMeasure();
-    },
-
-    removeMessage(id) {
-      startMeasure("remove message");
-      const index = this.messages.findIndex(m => m.id === id);
-      this.messages.splice(index, 1);
-      stopMeasure();
-    }
-  },
-  template: `
-    <div class="main">
-        <div class="left-thing">
-            <div>Number of msg: {{messages.length}}</div>
-            <button @click="addMessages(100)">Add 100 messages</button>
-            <button @click="addMessages(1000)">Add 1000 messages</button>
-            <button @click="addMessages(10000)">Add 10000 messages</button>
-            <button @click="addMessages(50000)">Add 50000 messages</button>
-            <button @click="updateSomeMessages">Update every 10th message</button>
-            <button @click="clear">Clear</button>
-        </div>
-        <div class="right-thing">
-            <div class="content">
-                <my-message v-for="msg in messages" v-bind:key="msg.id" v-bind:msg="msg" @removeMessage="removeMessage"></my-message>
-            </div>
-        </div>
-    </div>
-  `
-};
-
-//------------------------------------------------------------------------------
-// Application initialization
-//------------------------------------------------------------------------------
-
-new Vue({
-  render: h => h(App)
-}).$mount(`#main`);

extras/index.html

@@ -1,29 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>OWL Extras</title>
-</head>
-<body>
-  <h1>🦉 OWL Extra Stuff 🦉</h1>
-
-
-  <h2>Benchmarks</h2>
-  <p>The goal is to compare some operations on large lists</p>
-
-  <ul>
-    <li><a href="benchmarks/odoo-widgets-12.0">Odoo Widgets (12.0)</a></li>
-    <li><a href="benchmarks/odoo-widgets-12.3">Odoo Widgets (12.3)</a></li>
-    <li><a href="benchmarks/owl-0.7.0">OWL 0.7.0</a></li>
-    <li><a href="benchmarks/owl-0.8.0">OWL 0.8.0</a></li>
-    <li><a href="benchmarks/owl-0.9.0">OWL 0.9.0</a></li>
-    <li><a href="benchmarks/owl-0.10.0">OWL 0.10.0</a></li>
-    <li><a href="benchmarks/owl-master">OWL Master</a></li>
-    <li><a href="benchmarks/vue">Vue</a></li>
-    <li><a href="benchmarks/react">React</a></li>
-  </ul>
-
-  <h2>Playground</h2>
-  <a href="playground">Playground</a>
-</body>
-</html>

extras/readme.md

@@ -1,21 +0,0 @@
-# 🦉 Extra Stuff 🦉
-
-To help work/improve/learn with OWL, we have here:
-
-- a benchmarks application
-- a playground application
-
-Both of them can be accessed by using a static http server.  A simple python
-server is available in `server.py`.  There is also a npm script to start it:
-`npm run extras` (and its version with a watcher: `npm run extras:watch`).
-
-## Benchmarks
-
-The benchmarks application is a very small application, implemented in different
-frameworks, and in different versions of Owl.  This is a simple internal tool,
-useful to compare various performance metrics on some tasks.
-
-## Playground
-
-The playground is an important application designed to help learning and
-experimenting with Owl.  It is available [online](https://odoo.github.io/owl/playground/).

extras/server.py

@@ -1,38 +0,0 @@
-import sys
-import thread
-import webbrowser
-import time
-
-import BaseHTTPServer
-import SimpleHTTPServer
-
-HOST = '127.0.0.1'
-PORT = 8000
-URL = 'http://{0}:{1}/extras'.format(HOST, PORT)
-
-
-# We define our own handler here to remap owl.js GET requests to the Owl build
-# in dist/.  This is useful for the benchmarks and playground applications.
-# With this, we can simply copy the playground folder as is in the gh-page when
-# we want to update the playground.
-class OWLHandler(SimpleHTTPServer.SimpleHTTPRequestHandler):
-    def do_GET(self):
-        if self.path == '/extras/owl.js':
-            self.path = '/dist/owl.js'
-        return SimpleHTTPServer.SimpleHTTPRequestHandler.do_GET(self)
-
-
-def start_server():
-    httpd = BaseHTTPServer.HTTPServer((HOST, PORT), OWLHandler)
-    httpd.serve_forever()
-
-
-if __name__ == "__main__":
-    thread.start_new_thread(start_server, ())
-    webbrowser.open_new(URL)
-
-    while True:
-        try:
-            time.sleep(1)
-        except KeyboardInterrupt:
-            sys.exit(0)

package.json

@@ -1,54 +1,68 @@
 {
-  "name": "owl",
-  "version": "0.11.0",
+  "name": "@odoo/owl",
+  "version": "1.0.13",
   "description": "Odoo Web Library (OWL)",
-  "main": "src/index.ts",
+  "main": "dist/owl.cjs.js",
+  "browser": "dist/owl.iife.js",
+  "module": "dist/owl.es.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=10.15.3"
+  },
   "scripts": {
-    "build:js": "tsc --target esnext --module es6 --outDir dist/owl src/*",
     "build:bundle": "rollup -c",
-    "build": "npm run build:js && npm run build:bundle",
-    "minify": "uglifyjs dist/owl.js -o dist/owl.min.js --compress --mangle",
+    "build": "npm run build:bundle",
     "test": "jest",
     "test:watch": "jest --watch",
-    "extras:serve": "python extras/server.py",
-    "extras": "npm run build && npm run extras:serve",
-    "extras:watch": "npm-run-all  --parallel extras:serve \"build:* -- --watch\""
+    "tools:serve": "python3 tools/server.py || python tools/server.py",
+    "tools": "npm run build && npm run tools:serve",
+    "pretools:watch": "npm run build",
+    "tools:watch": "npm-run-all  --parallel tools:serve \"build:* -- --watch\"",
+    "prettier": "prettier {src/*.ts,src/**/*.ts,tests/*.ts,tests/**/*.ts,doc/*.md,doc/**/*.md} --write",
+    "publish": "npm run build && npm publish",
+    "release": "node tools/release.js"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/odoo/owl.git"
   },
   "author": "Odoo",
-  "license": "GPL-3.0-or-later",
+  "license": "LGPL-3.0-only",
   "bugs": {
     "url": "https://github.com/odoo/owl/issues"
   },
   "homepage": "https://github.com/odoo/owl#readme",
   "devDependencies": {
-    "@types/jest": "^23.3.12",
+    "@types/jest": "^27.0.1",
+    "@types/node": "^14.11.8",
+    "chalk": "^3.0.0",
     "cpx": "^1.5.0",
     "git-rev-sync": "^1.12.0",
-    "jest": "^23.6.0",
+    "github-api": "^3.3.0",
+    "jest": "^27.1.0",
+    "jest-environment-jsdom": "^27.1.0",
     "live-server": "^1.2.1",
     "npm-run-all": "^4.1.5",
-    "rollup": "^1.6.0",
-    "rollup-plugin-typescript2": "^0.20.1",
+    "prettier": "^2.0.4",
+    "rollup": "^2.56.3",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-typescript2": "^0.30.0",
     "sass": "^1.16.1",
-    "snabbdom-to-html": "^5.1.1",
     "source-map-support": "^0.5.10",
-    "ts-jest": "^23.10.5",
-    "typescript": "^3.2.2",
+    "ts-jest": "^27.0.5",
+    "typescript": "3.9.6",
     "uglify-es": "^3.3.9"
   },
-  "dependencies": {
-    "jest-environment-jsdom": "^24.7.1",
-    "snabbdom": "^0.7.3"
-  },
   "jest": {
+    "testEnvironment": "jsdom",
     "roots": [
       "<rootDir>/src",
       "<rootDir>/tests"
     ],
+    "setupFiles": ["./tests/mocks/mockEventTarget.js"],
     "transform": {
       "^.+\\.ts?$": "ts-jest"
     },
@@ -62,5 +76,9 @@
       "json",
       "node"
     ]
+  },
+  "prettier": {
+    "printWidth": 100,
+    "endOfLine": "auto"
   }
 }

roadmap.md

@@ -0,0 +1,28 @@
+# 🦉 OWL Roadmap 🦉
+
+- Current version: 1.0.13
+- Status: stable
+
+This roadmap is only an attempt at predicting Owl's future.  Everything may
+change!
+
+
+### 1.x
+
+- add chrome and firefox devtools,
+- fix every bugs,
+- improve documentation,
+- small backward compatible improvements.
+
+### 2.x (2020? 2021? 2022?)
+
+- stop support for `t-set` directive to define the content of a slot
+
+Maybe:
+
+- reimplement vdom to use *block* system, like Vue 3, which should make Owl
+  much faster
+- refactor `QWeb` to use an intermediate representation (some kind of AST) to
+  allow additional optimisations.
+
+

rollup.config.js

@@ -1,14 +1,71 @@
-import { version } from "./package.json";
+import pkg from "./package.json";
 import git from "git-rev-sync";
+import typescript from 'rollup-plugin-typescript2';
+import { terser } from "rollup-plugin-terser";
 
-// rollup.config.js
-export default {
-  input: "dist/owl/index.js",
-  output: {
-    file: "dist/owl.js",
-    format: "iife",
-    name: "owl",
-    extend: true,
-    outro: `exports._version = '${version}';\nexports._date = '${new Date().toISOString()}';\nexports._hash = '${git.short()}';\nexports._url = 'https://github.com/odoo/owl';`
+const name = "owl";
+const extend = true;
+
+/**
+ * Meta data to be added on the __info__ object.
+ * Used to let external tools know the current owl version.
+ */
+const outro = `
+__info__.version = '${pkg.version}';
+__info__.date = '${new Date().toISOString()}';
+__info__.hash = '${git.short()}';
+__info__.url = 'https://github.com/odoo/owl';
+`;
+
+/**
+ * Generate from a string depicting a path a new path for the minified version.
+ * @param {string} pkgFileName file name
+ */
+function generateMinifiedNameFromPkgName(pkgFileName) {
+  const parts = pkgFileName.split('.');
+  parts.splice(parts.length - 1, 0, "min");
+  return parts.join('.');
 }
+
+/**
+ * Get the rollup config based on the arguments
+ * @param {string} format format of the bundle
+ * @param {string} generatedFileName generated file name
+ * @param {boolean} minified should it be minified
+ */
+function getConfigForFormat(format, generatedFileName, minified = false) {
+  return {
+    file: minified ? generateMinifiedNameFromPkgName(generatedFileName) : generatedFileName,
+    format: format,
+    name: name,
+    extend: extend,
+    outro: outro,
+    freeze: false,
+    plugins: minified ? [terser()] : [],
+    indent: '    ', // indent with 4 spaces
+  };
+}
+
+export default {
+  input: "src/index.ts",
+  output: [
+
+    /**
+     * Read about module formats:
+     *  https://auth0.com/blog/javascript-module-systems-showdown/
+     *  https://medium.com/@kelin2025/so-you-wanna-use-es6-modules-714f48b3a953
+     */
+
+    getConfigForFormat('esm', pkg.module),
+    getConfigForFormat('esm', pkg.module, true),
+    getConfigForFormat('cjs', pkg.main),
+    getConfigForFormat('cjs', pkg.main, true),
+    getConfigForFormat('iife', pkg.browser),
+    getConfigForFormat('iife', pkg.browser, true),
+  ],
+  plugins: [
+    typescript({
+      useTsconfigDeclarationDir: true
+    }),
+  ]
 };

src/app.ts

@@ -0,0 +1,45 @@
+import { Component } from "./component/component";
+import { ComponentNode } from "./component/component_node";
+import { Scheduler } from "./component/scheduler";
+import { TemplateSet } from "./qweb/template_helpers";
+
+// reimplement dev mode stuff see last change in 0f7a8289a6fb8387c3c1af41c6664b2a8448758f
+
+export class App<T extends typeof Component = any> extends TemplateSet {
+  Root: T;
+  props: any;
+  env: any = {};
+  scheduler = new Scheduler(window.requestAnimationFrame.bind(window));
+  root: ComponentNode | null = null;
+  dev: boolean = true;
+
+  constructor(Root: T, props?: any) {
+    super();
+    this.Root = Root;
+    this.props = props;
+  }
+
+  configure(params: any) {
+    if (params.env) {
+      this.env = params.env;
+    }
+  }
+
+  mount(target: HTMLElement): Promise<InstanceType<T>> {
+    if (!(target instanceof HTMLElement)) {
+      throw new Error("Cannot mount component: the target is not a valid DOM element");
+    }
+    if (!document.body.contains(target)) {
+      throw new Error("Cannot mount a component on a detached dom node");
+    }
+    const node = new ComponentNode(this.Root, this.props, this);
+    this.root = node;
+    return node.mountComponent(target);
+  }
+
+  destroy() {
+    if (this.root) {
+      this.root.destroy();
+    }
+  }
+}

src/blockdom/attributes.ts

@@ -0,0 +1,155 @@
+import type { Setter } from "./block_compiler";
+
+const { setAttribute, removeAttribute } = Element.prototype;
+const tokenList = DOMTokenList.prototype;
+const tokenListAdd = tokenList.add;
+const tokenListRemove = tokenList.remove;
+const isArray = Array.isArray;
+const { split, trim } = String.prototype;
+const wordRegexp = /\s+/;
+
+/**
+ * We regroup here all code related to updating attributes in a very loose sense:
+ * attributes, properties and classs are all managed by the functions in this
+ * file.
+ */
+
+export function createAttrUpdater(attr: string): Setter<HTMLElement> {
+  return function (this: HTMLElement, value: any) {
+    if (value !== false) {
+      setAttribute.call(this, attr, value === true ? "" : value);
+    }
+  };
+}
+
+export function attrsSetter(this: HTMLElement, attrs: any) {
+  if (isArray(attrs)) {
+    setAttribute.call(this, attrs[0], attrs[1]);
+  } else {
+    for (let k in attrs) {
+      setAttribute.call(this, k, attrs[k]);
+    }
+  }
+}
+
+export function attrsUpdater(this: HTMLElement, attrs: any, oldAttrs: any) {
+  if (isArray(attrs)) {
+    const name = attrs[0];
+    const val = attrs[1];
+    if (name === oldAttrs[0]) {
+      if (val === oldAttrs[1]) {
+        return;
+      }
+      setAttribute.call(this, name, val);
+    } else {
+      removeAttribute.call(this, oldAttrs[0]);
+      setAttribute.call(this, name, val);
+    }
+  } else {
+    for (let k in oldAttrs) {
+      if (!(k in attrs)) {
+        removeAttribute.call(this, k);
+      }
+    }
+    for (let k in attrs) {
+      const val = attrs[k];
+      if (val !== oldAttrs[k]) {
+        setAttribute.call(this, k, val);
+      }
+    }
+  }
+}
+
+function toClassObj(expr: string | number | { [c: string]: any }) {
+  const result: { [c: string]: any } = {};
+  switch (typeof expr) {
+    case "string":
+      // we transform here a list of classes into an object:
+      //  'hey you' becomes {hey: true, you: true}
+      const str = trim.call(expr);
+      if (!str) {
+        return {};
+      }
+      let words = split.call(str, wordRegexp);
+      for (let i = 0, l = words.length; i < l; i++) {
+        result[words[i]] = true;
+      }
+      return result;
+    case "object":
+      // this is already an object but we may need to split keys:
+      // {'a': true, 'b c': true} should become {a: true, b: true, c: true}
+      for (let key in expr as any) {
+        const value = (expr as any)[key];
+        if (value) {
+          const words = split.call(key, wordRegexp);
+          for (let word of words) {
+            result[word] = value;
+          }
+        }
+      }
+      return result;
+
+    case "undefined":
+      return {};
+    case "number":
+      return { [expr as number]: true };
+    default:
+      return { [expr as any]: true };
+  }
+}
+
+export function setClass(this: HTMLElement, val: any) {
+  val = val === "" ? {} : toClassObj(val);
+  // add classes
+  const cl = this.classList;
+  for (let c in val) {
+    tokenListAdd.call(cl, c);
+  }
+}
+
+export function updateClass(this: HTMLElement, val: any, oldVal: any) {
+  oldVal = oldVal === "" ? {} : toClassObj(oldVal);
+  val = val === "" ? {} : toClassObj(val);
+  const cl = this.classList;
+  // remove classes
+  for (let c in oldVal) {
+    if (!(c in val)) {
+      tokenListRemove.call(cl, c);
+    }
+  }
+  // add classes
+  for (let c in val) {
+    if (!(c in oldVal)) {
+      tokenListAdd.call(cl, c);
+    }
+  }
+}
+
+export function makePropSetter(name: string): Setter<HTMLElement> {
+  return function setProp(this: HTMLElement, value: any) {
+    (this as any)[name] = value;
+  };
+}
+
+export function isProp(tag: string, key: string): boolean {
+  switch (tag) {
+    case "input":
+      return (
+        key === "checked" ||
+        key === "indeterminate" ||
+        key === "value" ||
+        key === "readonly" ||
+        key === "disabled"
+      );
+    case "option":
+      return key === "selected" || key === "disabled";
+    case "textarea":
+      return key === "readonly" || key === "disabled";
+      break;
+    case "button":
+    case "select":
+    case "optgroup":
+      return key === "disabled";
+  }
+  return false;
+}

src/blockdom/block_compiler.ts

@@ -0,0 +1,602 @@
+import {
+  attrsSetter,
+  attrsUpdater,
+  createAttrUpdater,
+  isProp,
+  makePropSetter,
+  setClass,
+  updateClass,
+} from "./attributes";
+import { config } from "./config";
+import { createEventHandler } from "./events";
+import type { VNode } from "./index";
+import { VMulti } from "./multi";
+import { toText } from "./text";
+
+const getDescriptor = (o: any, p: any) => Object.getOwnPropertyDescriptor(o, p)!;
+const nodeProto = Node.prototype;
+const elementProto = Element.prototype;
+const characterDataProto = CharacterData.prototype;
+
+const characterDataSetData = getDescriptor(characterDataProto, "data").set!;
+const nodeGetFirstChild = getDescriptor(nodeProto, "firstChild").get!;
+const nodeGetNextSibling = getDescriptor(nodeProto, "nextSibling").get!;
+
+const NO_OP = () => {};
+
+// -----------------------------------------------------------------------------
+// Main compiler code
+// -----------------------------------------------------------------------------
+
+type BlockType = (data?: any[], children?: VNode[]) => VNode;
+
+const cache: { [key: string]: BlockType } = {};
+
+/**
+ * Compiling blocks is a multi-step process:
+ *
+ * 1. build an IntermediateTree from the HTML element. This intermediate tree
+ *    is a binary tree structure that encode dynamic info sub nodes, and the
+ *    path required to reach them
+ * 2. process the tree to build a block context, which is an object that aggregate
+ *    all dynamic info in a list, and also, all ref indexes.
+ * 3. process the context to build appropriate builder/setter functions
+ * 4. make a dynamic block class, which will efficiently collect references and
+ *    create/update dynamic locations/children
+ *
+ * @param str
+ * @returns a new block type, that can build concrete blocks
+ */
+export function createBlock(str: string): BlockType {
+  if (str in cache) {
+    return cache[str];
+  }
+
+  // step 0: prepare html base element
+  const doc = new DOMParser().parseFromString(`<t>${str}</t>`, "text/xml");
+  const node = doc.firstChild!.firstChild!;
+  if (config.shouldNormalizeDom) {
+    normalizeNode(node as any);
+  }
+
+  // step 1: prepare intermediate tree
+  const tree = buildTree(node);
+
+  // step 2: prepare block context
+  const context = buildContext(tree);
+
+  // step 3: build the final block class
+  const template = tree.el as HTMLElement;
+  const Block = buildBlock(template, context);
+  cache[str] = Block;
+  return Block;
+}
+
+// -----------------------------------------------------------------------------
+// Helper
+// -----------------------------------------------------------------------------
+
+function normalizeNode(node: HTMLElement | Text) {
+  if (node.nodeType === Node.TEXT_NODE) {
+    if (!/\S/.test((node as Text).textContent!)) {
+      (node as Text).remove();
+      return;
+    }
+  }
+  if (node.nodeType === Node.ELEMENT_NODE) {
+    if ((node as HTMLElement).tagName === "pre") {
+      return;
+    }
+  }
+  for (let i = node.childNodes.length - 1; i >= 0; --i) {
+    normalizeNode(node.childNodes.item(i) as any);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// building a intermediate tree
+// -----------------------------------------------------------------------------
+
+interface DynamicInfo {
+  idx: number;
+  refIdx?: number;
+  type: "text" | "child" | "handler" | "attribute" | "attributes" | "ref";
+  isOnlyChild?: boolean;
+  name?: string;
+  tag?: string;
+  event?: string;
+}
+
+interface IntermediateTree {
+  parent: IntermediateTree | null;
+  firstChild: IntermediateTree | null;
+  nextSibling: IntermediateTree | null;
+  el: Node;
+  info: DynamicInfo[];
+  forceRef?: boolean;
+  refIdx?: number;
+  refN: number;
+}
+
+function buildTree(
+  node: Node,
+  parent: IntermediateTree | null = null,
+  domParentTree: IntermediateTree | null = null
+): IntermediateTree {
+  switch (node.nodeType) {
+    case 1: {
+      // HTMLElement
+      let isActive = false;
+      const tagName = (node as Element).tagName;
+      let el: Node | undefined = undefined;
+      const info: DynamicInfo[] = [];
+      if (tagName.startsWith("block-text-")) {
+        const index = parseInt(tagName.slice(11), 10);
+        info.push({ type: "text", idx: index });
+        el = document.createTextNode("");
+        isActive = true;
+      }
+      if (tagName.startsWith("block-child-")) {
+        domParentTree!.forceRef = true;
+        const index = parseInt(tagName.slice(12), 10);
+        info.push({ type: "child", idx: index });
+        el = document.createTextNode("");
+        isActive = true;
+      }
+      if (!el) {
+        el = document.createElement(tagName);
+      }
+      if (el instanceof HTMLElement) {
+        const attrs = (node as Element).attributes;
+        for (let i = 0; i < attrs.length; i++) {
+          const attrName = attrs[i].name;
+          const attrValue = attrs[i].value;
+          if (attrName.startsWith("block-handler-")) {
+            isActive = true;
+            const idx = parseInt(attrName.slice(14), 10);
+            info.push({
+              type: "handler",
+              idx,
+              event: attrValue,
+            });
+          } else if (attrName.startsWith("block-attribute-")) {
+            isActive = true;
+            const idx = parseInt(attrName.slice(16), 10);
+            info.push({
+              type: "attribute",
+              idx,
+              name: attrValue,
+              tag: tagName,
+            });
+          } else if (attrName === "block-attributes") {
+            isActive = true;
+            info.push({
+              type: "attributes",
+              idx: parseInt(attrValue, 10),
+            });
+          } else if (attrName === "block-ref") {
+            isActive = true;
+            info.push({
+              type: "ref",
+              idx: parseInt(attrValue, 10),
+            });
+          } else {
+            el.setAttribute(attrs[i].name, attrValue);
+          }
+        }
+      }
+
+      const tree: IntermediateTree = {
+        parent,
+        firstChild: null,
+        nextSibling: null,
+        el,
+        info,
+        refN: isActive ? 1 : 0,
+      };
+
+      if (node.firstChild) {
+        const childNode = node.childNodes[0];
+        if (
+          node.childNodes.length === 1 &&
+          childNode.nodeType === 1 &&
+          (childNode as Element).tagName.startsWith("block-child-")
+        ) {
+          const tagName = (childNode as Element).tagName;
+          const index = parseInt(tagName.slice(12), 10);
+          info.push({ idx: index, type: "child", isOnlyChild: true });
+          isActive = true;
+          tree.refN = 1;
+        } else {
+          tree.firstChild = buildTree(node.firstChild, tree, tree);
+          el.appendChild(tree.firstChild.el);
+          let curNode: Node | null = node.firstChild;
+          let curTree: IntermediateTree | null = tree.firstChild;
+          while ((curNode = curNode.nextSibling)) {
+            curTree.nextSibling = buildTree(curNode, curTree, tree);
+            el.appendChild(curTree.nextSibling.el);
+            curTree = curTree.nextSibling;
+          }
+        }
+      }
+      if (isActive) {
+        let cur: IntermediateTree | null = tree;
+        while ((cur = cur.parent)) {
+          cur.refN++;
+        }
+      }
+      return tree;
+    }
+    case 3:
+    case 8: {
+      // text node or comment node
+      const el =
+        node.nodeType === 3
+          ? document.createTextNode(node.textContent!)
+          : document.createComment(node.textContent!);
+      return {
+        parent: parent,
+        firstChild: null,
+        nextSibling: null,
+        el,
+        info: [],
+        refN: 0,
+      };
+    }
+  }
+  throw new Error("boom");
+}
+
+function parentTree(tree: IntermediateTree): IntermediateTree | null {
+  let parent = tree.parent;
+  while (parent && parent.nextSibling === tree) {
+    tree = parent;
+    parent = parent.parent;
+  }
+  return parent;
+}
+
+// -----------------------------------------------------------------------------
+// Building a block context
+// -----------------------------------------------------------------------------
+
+interface RefCollector {
+  idx: number;
+  prevIdx: number;
+  getVal: Function;
+}
+
+export type Setter<T = any> = (this: T, value: any) => void;
+export type Updater<T = any> = (this: T, value: any, oldVal: any) => void;
+
+interface Location {
+  refIdx: number;
+  setData: Setter;
+  updateData: Updater;
+}
+
+interface IndexedLocation extends Location {
+  idx: number;
+}
+
+interface Child {
+  parentRefIdx: number;
+  afterRefIdx?: number;
+  isOnlyChild?: boolean;
+}
+
+interface BlockCtx {
+  refN: number;
+  collectors: RefCollector[];
+  locations: IndexedLocation[];
+  children: Child[];
+  cbRefs: number[];
+}
+
+function buildContext(
+  tree: IntermediateTree,
+  ctx?: BlockCtx,
+  fromIdx?: number,
+  toIdx?: number
+): BlockCtx {
+  if (!ctx) {
+    const children = new Array(tree.info.filter((v) => v.type === "child").length);
+    ctx = { collectors: [], locations: [], children, cbRefs: [], refN: tree.refN };
+    fromIdx = 0;
+    toIdx = tree.refN - 1;
+  }
+  if (tree.refN) {
+    const initialIdx = fromIdx!;
+    const isRef = tree.forceRef || tree.info.length > 0;
+    const firstChild = tree.firstChild ? tree.firstChild.refN : 0;
+    const nextSibling = tree.nextSibling ? tree.nextSibling.refN : 0;
+
+    //node
+    if (isRef) {
+      for (let info of tree.info) {
+        info.refIdx = initialIdx!;
+      }
+      tree.refIdx = initialIdx!;
+      updateCtx(ctx, tree);
+      fromIdx!++;
+    }
+
+    // right
+    if (nextSibling) {
+      const idx = fromIdx! + firstChild;
+      ctx.collectors.push({ idx, prevIdx: initialIdx, getVal: nodeGetNextSibling });
+      buildContext(tree.nextSibling!, ctx, idx, toIdx);
+    }
+
+    // left
+    if (firstChild) {
+      ctx.collectors.push({ idx: fromIdx!, prevIdx: initialIdx, getVal: nodeGetFirstChild });
+      buildContext(tree.firstChild!, ctx, fromIdx!, toIdx! - nextSibling);
+    }
+  }
+
+  return ctx;
+}
+
+function updateCtx(ctx: BlockCtx, tree: IntermediateTree) {
+  for (let info of tree.info) {
+    switch (info.type) {
+      case "text":
+        ctx.locations.push({
+          idx: info.idx,
+          refIdx: info.refIdx!,
+          setData: setText,
+          updateData: setText,
+        });
+        break;
+      case "child":
+        if (info.isOnlyChild) {
+          // tree is the parentnode here
+          ctx.children[info.idx] = {
+            parentRefIdx: info.refIdx!,
+            isOnlyChild: true,
+          };
+        } else {
+          // tree is the anchor text node
+          ctx.children[info.idx] = {
+            parentRefIdx: parentTree(tree)!.refIdx!,
+            afterRefIdx: info.refIdx!,
+          };
+        }
+        break;
+      case "attribute": {
+        const refIdx = info.refIdx!;
+        let updater: any;
+        let setter: any;
+        if (isProp(info.tag!, info.name!)) {
+          const setProp = makePropSetter(info.name!);
+          setter = setProp;
+          updater = setProp;
+        } else if (info.name === "class") {
+          setter = setClass;
+          updater = updateClass;
+        } else {
+          setter = createAttrUpdater(info.name!);
+          updater = setter;
+        }
+        ctx.locations.push({
+          idx: info.idx,
+          refIdx,
+          setData: setter,
+          updateData: updater,
+        });
+        break;
+      }
+      case "attributes":
+        ctx.locations.push({
+          idx: info.idx,
+          refIdx: info.refIdx!,
+          setData: attrsSetter,
+          updateData: attrsUpdater,
+        });
+        break;
+      case "handler": {
+        const setupHandler = createEventHandler(info.event!);
+        ctx.locations.push({
+          idx: info.idx,
+          refIdx: info.refIdx!,
+          setData: setupHandler,
+          updateData: setupHandler,
+        });
+        break;
+      }
+      case "ref":
+        ctx.cbRefs.push(info.idx);
+        ctx.locations.push({
+          idx: info.idx,
+          refIdx: info.refIdx!,
+          setData: setRef,
+          updateData: NO_OP,
+        });
+    }
+  }
+}
+// -----------------------------------------------------------------------------
+// building the concrete block class
+// -----------------------------------------------------------------------------
+
+function buildBlock(template: HTMLElement, ctx: BlockCtx): BlockType {
+  let B = createBlockClass(template, ctx);
+
+  if (ctx.cbRefs.length) {
+    const refs = ctx.cbRefs;
+    B = class extends B {
+      remove() {
+        super.remove();
+        for (let ref of refs) {
+          let fn = (this as any).data[ref];
+          fn(null);
+        }
+      }
+    };
+  }
+
+  if (ctx.children.length) {
+    B = class extends B {
+      children: (VNode | undefined)[] | undefined;
+      constructor(data?: any[], children?: VNode[]) {
+        super(data);
+        this.children = children;
+      }
+    };
+    B.prototype.beforeRemove = VMulti.prototype.beforeRemove;
+    return (data?: any[], children: (VNode | undefined)[] = []) => new B(data, children);
+  }
+
+  return (data?: any[]) => new B(data);
+}
+
+type Constructor<T> = new (...args: any[]) => T;
+type BlockClass = Constructor<VNode<any>>;
+
+function createBlockClass(template: HTMLElement, ctx: BlockCtx): BlockClass {
+  const { refN, collectors, children } = ctx;
+  const colN = collectors.length;
+  ctx.locations.sort((a, b) => a.idx - b.idx);
+  const locations: Location[] = ctx.locations.map((loc) => ({
+    refIdx: loc.refIdx,
+    setData: loc.setData,
+    updateData: loc.updateData,
+  }));
+  const locN = locations.length;
+  const childN = children.length;
+  const childrenLocs = children;
+  const isDynamic = refN > 0;
+
+  // these values are defined here to make them faster to lookup in the class
+  // block scope
+  const nodeCloneNode = nodeProto.cloneNode;
+  const nodeInsertBefore = nodeProto.insertBefore;
+  const elementRemove = elementProto.remove;
+
+  return class Block {
+    el: HTMLElement | undefined;
+    refs: Node[] | undefined;
+    data: any[] | undefined;
+    parentEl?: HTMLElement | undefined;
+    children?: (VNode | undefined)[];
+
+    constructor(data?: any[]) {
+      this.data = data;
+    }
+
+    beforeRemove() {}
+
+    remove() {
+      elementRemove.call(this.el);
+    }
+
+    firstNode(): Node {
+      return this.el!;
+    }
+
+    moveBefore(other: Block | null, afterNode: Node | null) {
+      const target = other ? other.el! : afterNode;
+      nodeInsertBefore.call(this.parentEl, this.el!, target);
+    }
+
+    mount(parent: HTMLElement, afterNode: Node | null) {
+      const el = nodeCloneNode.call(template, true);
+      nodeInsertBefore.call(parent, el, afterNode);
+      if (isDynamic) {
+        // collecting references
+        const refs: Node[] = new Array(refN);
+        this.refs = refs;
+        refs[0] = el;
+        for (let i = 0; i < colN; i++) {
+          const w = collectors[i];
+          refs[w.idx] = w.getVal.call(refs[w.prevIdx]);
+        }
+
+        // applying data to all update points
+        if (locN) {
+          const data = this.data!;
+          for (let i = 0; i < locN; i++) {
+            const loc = locations[i];
+            loc.setData.call(refs[loc.refIdx], data[i]);
+          }
+        }
+
+        // preparing all children
+        if (childN) {
+          const children = this.children;
+          for (let i = 0; i < childN; i++) {
+            const child = children![i];
+            if (child) {
+              const loc = childrenLocs[i];
+              const afterNode = loc.afterRefIdx ? refs[loc.afterRefIdx] : null;
+              child.isOnlyChild = loc.isOnlyChild;
+              child.mount(refs[loc.parentRefIdx] as any, afterNode);
+            }
+          }
+        }
+      }
+      this.el = el as HTMLElement;
+      this.parentEl = parent;
+    }
+    patch(other: Block, withBeforeRemove: boolean) {
+      if (this === other) {
+        return;
+      }
+      const refs = this.refs!;
+      // update texts/attributes/
+      if (locN) {
+        const data1 = this.data!;
+        const data2 = other.data!;
+        for (let i = 0; i < locN; i++) {
+          const val1 = data1[i];
+          const val2 = data2[i];
+          if (val1 !== val2) {
+            const loc = locations[i];
+            loc.updateData.call(refs[loc.refIdx], val2, val1);
+          }
+        }
+        this.data = data2;
+      }
+
+      // update children
+      if (childN) {
+        let children1 = this.children;
+        const children2 = other.children;
+        for (let i = 0; i < childN; i++) {
+          const child1 = children1![i];
+          const child2 = children2![i];
+          if (child1) {
+            if (child2) {
+              child1.patch(child2, withBeforeRemove);
+            } else {
+              if (withBeforeRemove) {
+                child1.beforeRemove();
+              }
+              child1.remove();
+              children1![i] = undefined;
+            }
+          } else if (child2) {
+            const loc = childrenLocs[i];
+            const afterNode = loc.afterRefIdx ? refs[loc.afterRefIdx] : null;
+            child2.mount(refs[loc.parentRefIdx] as any, afterNode);
+            children1![i] = child2;
+          }
+        }
+      }
+    }
+    toString() {
+      const div = document.createElement("div");
+      this.mount(div, null);
+      return div.innerHTML;
+    }
+  };
+}
+
+function setText(this: Text, value: any) {
+  characterDataSetData.call(this, toText(value));
+}
+
+function setRef(this: HTMLElement, fn: any) {
+  fn(this);
+}

src/blockdom/config.ts

@@ -0,0 +1,16 @@
+export const config = {
+  // whether or not blockdom should normalize DOM whenever a block is created.
+  // Normalizing dom mean removing empty text nodes (or containing only spaces)
+  shouldNormalizeDom: true,
+
+  // this is the main event handler. Every event handler registered with blockdom
+  // will go through this function, giving it the data registered in the block
+  // and the event
+  mainEventHandler: (data: any, ev: Event) => {
+    if (typeof data === "function") {
+      data(ev);
+    } else if (Array.isArray(data)) {
+      data[0](data[1], ev);
+    }
+  },
+};

src/blockdom/events.ts

@@ -0,0 +1,32 @@
+import { config } from "./config";
+
+export function createEventHandler(event: string) {
+  setupSyntheticEvent(event);
+  const key = `__event__${event}`;
+  return function setupHandler(this: HTMLElement, data: any) {
+    (this as any)[key] = data;
+  };
+}
+
+function nativeToSyntheticEvent(event: Event, name: string) {
+  const eventKey = `__event__${name}`;
+  let dom = event.target;
+  while (dom !== null) {
+    const data = (dom as any)[eventKey];
+    if (data) {
+      config.mainEventHandler(data, event);
+      return;
+    }
+    dom = (dom as any).parentNode;
+  }
+}
+
+const CONFIGURED_SYNTHETIC_EVENTS: { [event: string]: boolean } = {};
+
+function setupSyntheticEvent(name: string) {
+  if (CONFIGURED_SYNTHETIC_EVENTS[name]) {
+    return;
+  }
+  document.addEventListener(name, (event) => nativeToSyntheticEvent(event, name));
+  CONFIGURED_SYNTHETIC_EVENTS[name] = true;
+}

src/blockdom/html.ts

@@ -0,0 +1,87 @@
+import type { VNode } from "./index";
+
+const nodeProto = Node.prototype;
+
+const nodeInsertBefore = nodeProto.insertBefore;
+const nodeRemoveChild = nodeProto.removeChild;
+
+class VHtml {
+  html: string;
+  parentEl?: HTMLElement | undefined;
+  content: ChildNode[] = [];
+
+  constructor(html: string) {
+    this.html = html;
+  }
+
+  mount(parent: HTMLElement, afterNode: Node | null) {
+    this.parentEl = parent;
+    const template = document.createElement("template");
+    template.innerHTML = this.html;
+    this.content = [...(template.content.childNodes as any)];
+    for (let elem of this.content) {
+      nodeInsertBefore.call(parent, elem, afterNode);
+    }
+    if (!this.content.length) {
+      const textNode = document.createTextNode("");
+      this.content.push(textNode);
+      nodeInsertBefore.call(parent, textNode, afterNode);
+    }
+  }
+
+  moveBefore(other: VHtml | null, afterNode: Node | null) {
+    const target = other ? other.content[0] : afterNode;
+    const parent = this.parentEl;
+    for (let elem of this.content) {
+      nodeInsertBefore.call(parent, elem, target);
+    }
+  }
+
+  patch(other: VHtml) {
+    if (this === other) {
+      return;
+    }
+    const html2 = other.html;
+    if (this.html !== html2) {
+      const parent = this.parentEl;
+      // insert new html in front of current
+      const afterNode = this.content[0];
+      const template = document.createElement("template");
+      template.innerHTML = html2;
+      const content = [...(template.content.childNodes as any)];
+      for (let elem of content) {
+        nodeInsertBefore.call(parent, elem, afterNode);
+      }
+      if (!content.length) {
+        const textNode = document.createTextNode("");
+        content.push(textNode);
+        nodeInsertBefore.call(parent, textNode, afterNode);
+      }
+
+      // remove current content
+      this.remove();
+      this.content = content;
+    }
+  }
+
+  beforeRemove() {}
+
+  remove() {
+    const parent = this.parentEl;
+    for (let elem of this.content) {
+      nodeRemoveChild.call(parent, elem);
+    }
+  }
+
+  firstNode(): Node {
+    return this.content[0]!;
+  }
+
+  toString() {
+    return this.html;
+  }
+}
+
+export function html(str: string): VNode<VHtml> {
+  return new VHtml(str);
+}

src/blockdom/index.ts

@@ -0,0 +1,44 @@
+export { config } from "./config";
+
+export { toggler } from "./toggler";
+export { createBlock } from "./block_compiler";
+export { list } from "./list";
+export { multi } from "./multi";
+export { text } from "./text";
+export { html } from "./html";
+
+export interface VNode<T = any> {
+  mount(parent: HTMLElement, afterNode: Node | null): void;
+  moveBefore(other: T | null, afterNode: Node | null): void;
+  patch(other: T, withBeforeRemove: boolean): void;
+  beforeRemove(): void;
+  remove(): void;
+  firstNode(): Node | undefined;
+
+  el?: undefined | HTMLElement | Text;
+  parentEl?: undefined | HTMLElement;
+  isOnlyChild?: boolean | undefined;
+  key?: any;
+}
+
+export type BDom = VNode<any>;
+
+export function mount(vnode: VNode, fixture: HTMLElement) {
+  vnode.mount(fixture, null);
+}
+
+export function patch(vnode1: VNode, vnode2: VNode, withBeforeRemove: boolean = false) {
+  vnode1.patch(vnode2, withBeforeRemove);
+}
+
+export function remove(vnode: VNode, withBeforeRemove: boolean = false) {
+  if (withBeforeRemove) {
+    vnode.beforeRemove();
+  }
+  vnode.remove();
+}
+
+export function withKey(vnode: VNode, key: any) {
+  vnode.key = key;
+  return vnode;
+}

src/blockdom/list.ts

@@ -0,0 +1,240 @@
+import type { VNode } from "./index";
+
+const getDescriptor = (o: any, p: any) => Object.getOwnPropertyDescriptor(o, p)!;
+const nodeProto = Node.prototype;
+
+const nodeInsertBefore = nodeProto.insertBefore;
+const nodeAppendChild = nodeProto.appendChild;
+const nodeRemoveChild = nodeProto.removeChild;
+const nodeSetTextContent = getDescriptor(nodeProto, "textContent").set!;
+
+// -----------------------------------------------------------------------------
+// List Node
+// -----------------------------------------------------------------------------
+
+class VList {
+  children: VNode[];
+  anchor: Node | undefined;
+  parentEl?: HTMLElement | undefined;
+  isOnlyChild?: boolean | undefined;
+
+  constructor(children: VNode[]) {
+    this.children = children;
+  }
+
+  mount(parent: HTMLElement, afterNode: Node | null) {
+    const children = this.children;
+    const _anchor = document.createTextNode("");
+    this.anchor = _anchor;
+    nodeInsertBefore.call(parent, _anchor, afterNode);
+    const l = children.length;
+    if (l) {
+      const mount = children[0].mount;
+      for (let i = 0; i < l; i++) {
+        mount.call(children[i], parent, _anchor);
+      }
+    }
+
+    this.parentEl = parent;
+  }
+
+  moveBefore(other: VList | null, afterNode: Node | null) {
+    if (other) {
+      const next = other!.children[0];
+      afterNode = (next ? next.firstNode() : other!.anchor) || null;
+    }
+    const children = this.children;
+    for (let i = 0, l = children.length; i < l; i++) {
+      children[i].moveBefore(null, afterNode);
+    }
+    this.parentEl!.insertBefore(this.anchor!, afterNode);
+  }
+
+  patch(other: VList, withBeforeRemove: boolean) {
+    if (this === other) {
+      return;
+    }
+    const ch1 = this.children;
+    const ch2: VNode[] = other.children;
+    if (ch2.length === 0 && ch1.length === 0) {
+      return;
+    }
+    this.children = ch2;
+    const proto = ch2[0] || ch1[0];
+    const {
+      mount: cMount,
+      patch: cPatch,
+      remove: cRemove,
+      beforeRemove,
+      moveBefore: cMoveBefore,
+      firstNode: cFirstNode,
+    } = proto;
+
+    const _anchor = this.anchor!;
+    const isOnlyChild = this.isOnlyChild;
+    const parent = this.parentEl!;
+
+    // fast path: no new child => only remove
+    if (ch2.length === 0 && isOnlyChild) {
+      if (withBeforeRemove) {
+        for (let i = 0, l = ch1.length; i < l; i++) {
+          beforeRemove.call(ch1[i]);
+        }
+      }
+
+      nodeSetTextContent.call(parent, "");
+      nodeAppendChild.call(parent, _anchor);
+      return;
+    }
+
+    let startIdx1 = 0;
+    let startIdx2 = 0;
+    let startVn1 = ch1[0];
+    let startVn2 = ch2[0];
+
+    let endIdx1 = ch1.length - 1;
+    let endIdx2 = ch2.length - 1;
+    let endVn1 = ch1[endIdx1];
+    let endVn2 = ch2[endIdx2];
+
+    let mapping: any = undefined;
+    // let noFullRemove = this.hasNoComponent;
+
+    while (startIdx1 <= endIdx1 && startIdx2 <= endIdx2) {
+      // -------------------------------------------------------------------
+      if (startVn1 === null) {
+        startVn1 = ch1[++startIdx1];
+        continue;
+      }
+      // -------------------------------------------------------------------
+      if (endVn1 === null) {
+        endVn1 = ch1[--endIdx1];
+        continue;
+      }
+      // -------------------------------------------------------------------
+      let startKey1 = startVn1.key;
+      let startKey2 = startVn2.key;
+      if (startKey1 === startKey2) {
+        cPatch.call(startVn1, startVn2, withBeforeRemove);
+        ch2[startIdx2] = startVn1;
+        startVn1 = ch1[++startIdx1];
+        startVn2 = ch2[++startIdx2];
+        continue;
+      }
+      // -------------------------------------------------------------------
+      let endKey1 = endVn1.key;
+      let endKey2 = endVn2.key;
+      if (endKey1 === endKey2) {
+        cPatch.call(endVn1, endVn2, withBeforeRemove);
+        ch2[endIdx2] = endVn1;
+        endVn1 = ch1[--endIdx1];
+        endVn2 = ch2[--endIdx2];
+        continue;
+      }
+      // -------------------------------------------------------------------
+      if (startKey1 === endKey2) {
+        // bnode moved right
+        cPatch.call(startVn1, endVn2, withBeforeRemove);
+        ch2[endIdx2] = startVn1;
+        const nextChild = ch2[endIdx2 + 1];
+        cMoveBefore.call(startVn1, nextChild, _anchor);
+        startVn1 = ch1[++startIdx1];
+        endVn2 = ch2[--endIdx2];
+        continue;
+      }
+      // -------------------------------------------------------------------
+      if (endKey1 === startKey2) {
+        // bnode moved left
+        cPatch.call(endVn1, startVn2, withBeforeRemove);
+        ch2[startIdx2] = endVn1;
+        const nextChild = ch1[startIdx1];
+        cMoveBefore.call(endVn1, nextChild, _anchor);
+        endVn1 = ch1[--endIdx1];
+        startVn2 = ch2[++startIdx2];
+        continue;
+      }
+      // -------------------------------------------------------------------
+      mapping = mapping || createMapping(ch1, startIdx1, endIdx1);
+      let idxInOld = mapping[startKey2];
+      if (idxInOld === undefined) {
+        cMount.call(startVn2, parent, cFirstNode.call(startVn1) || null);
+      } else {
+        const elmToMove = ch1[idxInOld];
+        cMoveBefore.call(elmToMove, startVn1, null);
+        cPatch.call(elmToMove, startVn2, withBeforeRemove);
+        ch2[startIdx2] = elmToMove;
+        ch1[idxInOld] = null as any;
+      }
+      startVn2 = ch2[++startIdx2];
+    }
+    // ---------------------------------------------------------------------
+    if (startIdx1 <= endIdx1 || startIdx2 <= endIdx2) {
+      if (startIdx1 > endIdx1) {
+        const nextChild = ch2[endIdx2 + 1];
+        const anchor = nextChild ? cFirstNode.call(nextChild) || null : _anchor;
+        for (let i = startIdx2; i <= endIdx2; i++) {
+          cMount.call(ch2[i], parent, anchor);
+        }
+      } else {
+        for (let i = startIdx1; i <= endIdx1; i++) {
+          let ch = ch1[i];
+          if (ch) {
+            if (withBeforeRemove) {
+              beforeRemove.call(ch);
+            }
+            cRemove.call(ch);
+          }
+        }
+      }
+    }
+  }
+
+  beforeRemove() {
+    const children = this.children;
+    const l = children.length;
+    if (l) {
+      const beforeRemove = children[0].beforeRemove;
+      for (let i = 0; i < l; i++) {
+        beforeRemove.call(children[i]);
+      }
+    }
+  }
+
+  remove() {
+    const { parentEl, anchor } = this;
+    if (this.isOnlyChild) {
+      nodeSetTextContent.call(parentEl, "");
+    } else {
+      const children = this.children;
+      const l = children.length;
+      if (l) {
+        const remove = children[0].remove;
+        for (let i = 0; i < l; i++) {
+          remove.call(children[i]);
+        }
+      }
+      nodeRemoveChild.call(parentEl, anchor!);
+    }
+  }
+
+  firstNode(): Node | undefined {
+    const child = this.children[0];
+    return child ? child.firstNode() : undefined;
+  }
+
+  toString(): string {
+    return this.children.map((c) => c!.toString()).join("");
+  }
+}
+
+export function list(children: VNode[]): VNode<VList> {
+  return new VList(children);
+}
+
+function createMapping(ch1: any[], startIdx1: number, endIdx2: number): { [key: string]: any } {
+  let mapping: any = {};
+  for (let i = startIdx1; i <= endIdx2; i++) {
+    mapping[ch1[i].key] = i;
+  }
+  return mapping;
+}

src/blockdom/multi.ts

@@ -0,0 +1,134 @@
+import type { VNode } from "./index";
+
+const getDescriptor = (o: any, p: any) => Object.getOwnPropertyDescriptor(o, p)!;
+const nodeProto = Node.prototype;
+const nodeInsertBefore = nodeProto.insertBefore;
+const nodeSetTextContent = getDescriptor(nodeProto, "textContent").set!;
+const nodeRemoveChild = nodeProto.removeChild;
+
+// -----------------------------------------------------------------------------
+// Multi NODE
+// -----------------------------------------------------------------------------
+
+export class VMulti {
+  children: (VNode | undefined)[];
+  anchors?: Node[] | undefined;
+  parentEl?: HTMLElement | undefined;
+  isOnlyChild?: boolean | undefined;
+
+  constructor(children: (VNode | undefined)[]) {
+    this.children = children;
+  }
+
+  mount(parent: HTMLElement, afterNode: Node | null) {
+    const children = this.children;
+    const l = children.length;
+    const anchors = new Array(l);
+    for (let i = 0; i < l; i++) {
+      let child = children[i];
+      if (child) {
+        child.mount(parent, afterNode);
+      } else {
+        const childAnchor = document.createTextNode("");
+        anchors[i] = childAnchor;
+        nodeInsertBefore.call(parent, childAnchor, afterNode);
+      }
+    }
+    this.anchors = anchors;
+    this.parentEl = parent;
+  }
+
+  moveBefore(other: VMulti | null, afterNode: Node | null) {
+    if (other) {
+      const next = other!.children[0];
+      afterNode = (next ? next.firstNode() : other!.anchors![0]) || null;
+    }
+    const children = this.children;
+    const parent = this.parentEl;
+    const anchors = this.anchors;
+    for (let i = 0, l = children.length; i < l; i++) {
+      let child = children[i];
+      if (child) {
+        child.moveBefore(null, afterNode);
+      } else {
+        const anchor = anchors![i];
+        nodeInsertBefore.call(parent, anchor, afterNode);
+      }
+    }
+  }
+
+  patch(other: VMulti, withBeforeRemove: boolean) {
+    if (this === other) {
+      return;
+    }
+    const children1 = this.children;
+    const children2 = other.children;
+    const anchors = this.anchors!;
+    const parentEl = this.parentEl!;
+    for (let i = 0, l = children1.length; i < l; i++) {
+      const vn1 = children1[i];
+      const vn2 = children2[i];
+      if (vn1) {
+        if (vn2) {
+          vn1.patch(vn2, withBeforeRemove);
+        } else {
+          const afterNode = vn1.firstNode()!;
+          const anchor = document.createTextNode("");
+          anchors[i] = anchor;
+          nodeInsertBefore.call(parentEl, anchor, afterNode);
+          if (withBeforeRemove) {
+            vn1.beforeRemove();
+          }
+          vn1.remove();
+          children1[i] = undefined;
+        }
+      } else if (vn2) {
+        children1[i] = vn2;
+        const anchor = anchors[i];
+        vn2.mount(parentEl, anchor);
+        nodeRemoveChild.call(parentEl, anchor);
+      }
+    }
+  }
+
+  beforeRemove() {
+    const children = this.children;
+    for (let i = 0, l = children.length; i < l; i++) {
+      const child = children[i];
+      if (child) {
+        child.beforeRemove();
+      }
+    }
+  }
+
+  remove() {
+    const parentEl = this.parentEl;
+    if (this.isOnlyChild) {
+      nodeSetTextContent.call(parentEl, "");
+    } else {
+      const children = this.children;
+      const anchors = this.anchors;
+      for (let i = 0, l = children.length; i < l; i++) {
+        const child = children[i];
+        if (child) {
+          child.remove();
+        } else {
+          nodeRemoveChild.call(parentEl, anchors![i]);
+        }
+      }
+    }
+  }
+
+  firstNode(): Node | undefined {
+    const child = this.children[0];
+    return child ? child.firstNode() : this.anchors![0];
+  }
+
+  toString(): string {
+    return this.children.map((c) => c!.toString()).join("");
+  }
+}
+
+export function multi(children: (VNode | undefined)[]): VNode<VMulti> {
+  return new VMulti(children);
+}

src/blockdom/text.ts

@@ -0,0 +1,70 @@
+import type { VNode } from "./index";
+
+const getDescriptor = (o: any, p: any) => Object.getOwnPropertyDescriptor(o, p)!;
+const nodeProto = Node.prototype;
+const characterDataProto = CharacterData.prototype;
+
+const nodeInsertBefore = nodeProto.insertBefore;
+const characterDataSetData = getDescriptor(characterDataProto, "data").set!;
+const nodeRemoveChild = nodeProto.removeChild;
+
+class VText {
+  text: string;
+  parentEl?: HTMLElement | undefined;
+  el?: Text;
+
+  constructor(text: string) {
+    this.text = text;
+  }
+
+  mount(parent: HTMLElement, afterNode: Node | null) {
+    this.parentEl = parent;
+    const node = document.createTextNode(toText(this.text));
+    nodeInsertBefore.call(parent, node, afterNode);
+    this.el = node;
+  }
+
+  moveBefore(other: VText | null, afterNode: Node | null) {
+    const target = other ? other.el! : afterNode;
+    nodeInsertBefore.call(this.parentEl, this.el!, target);
+  }
+
+  patch(other: VText) {
+    const text2 = other.text;
+    if (this.text !== text2) {
+      characterDataSetData.call(this.el!, toText(text2));
+      this.text = text2;
+    }
+  }
+
+  beforeRemove() {}
+
+  remove() {
+    nodeRemoveChild.call(this.parentEl, this.el!);
+  }
+
+  firstNode(): Node {
+    return this.el!;
+  }
+
+  toString() {
+    return this.text;
+  }
+}
+
+export function text(str: string): VNode<VText> {
+  return new VText(str);
+}
+
+export function toText(value: any): string {
+  switch (typeof value) {
+    case "string":
+      return value;
+    case "number":
+      return String(value);
+    case "boolean":
+      return value ? "true" : "false";
+    default:
+      return value || "";
+  }
+}

src/blockdom/toggler.ts

@@ -0,0 +1,63 @@
+import type { VNode } from "./index";
+
+// -----------------------------------------------------------------------------
+// Toggler node
+// -----------------------------------------------------------------------------
+
+class VToggler {
+  key: string;
+  child: VNode;
+
+  parentEl?: HTMLElement | undefined;
+
+  constructor(key: string, child: VNode) {
+    this.key = key;
+    this.child = child;
+  }
+
+  mount(parent: HTMLElement, afterNode: Node | null) {
+    this.parentEl = parent;
+    this.child.mount(parent, afterNode);
+  }
+
+  moveBefore(other: VToggler | null, afterNode: Node | null) {
+    this.child.moveBefore(other ? other.child : null, afterNode);
+  }
+
+  patch(other: VToggler, withBeforeRemove: boolean) {
+    if (this === other) {
+      return;
+    }
+    let child1 = this.child;
+    let child2 = other.child;
+    if (this.key === other.key) {
+      child1.patch(child2, withBeforeRemove);
+    } else {
+      child2.mount(this.parentEl!, child1.firstNode()!);
+      if (withBeforeRemove) {
+        child1.beforeRemove();
+      }
+      child1.remove();
+      this.child = child2;
+      this.key = other.key;
+    }
+  }
+
+  beforeRemove() {}
+
+  remove() {
+    this.child.remove();
+  }
+
+  firstNode(): Node | undefined {
+    return this.child.firstNode();
+  }
+
+  toString(): string {
+    return this.child.toString();
+  }
+}
+
+export function toggler(key: string, child: VNode): VNode<VToggler> {
+  return new VToggler(key, child);
+}

src/component.ts

@@ -1,480 +0,0 @@
-import { EventBus } from "./event_bus";
-import { Observer } from "./observer";
-import { QWeb, CompiledTemplate } from "./qweb_core";
-import { h, patch, VNode } from "./vdom";
-
-/**
- * Owl Component System
- *
- * This file introduces a declarative and composable component system. It
- * contains:
- *
- * - the Env interface (generic type for the environment)
- * - the Meta interface (the owl specific metadata attached to a component)
- * - the Component class
- */
-
-//------------------------------------------------------------------------------
-// Types/helpers
-//------------------------------------------------------------------------------
-
-export interface Env {
-  qweb: QWeb;
-}
-
-export interface Meta<T extends Env, Props> {
-  readonly id: number;
-  vnode: VNode | null;
-  isMounted: boolean;
-  isDestroyed: boolean;
-  parent: Component<T, any, any> | null;
-  children: { [key: number]: Component<T, any, any> };
-  // children mapping: from templateID to widgetID
-  // should it be a map number => Widget?
-  cmap: { [key: number]: number };
-
-  renderId: number;
-  renderProps: Props | null;
-  renderPromise: Promise<VNode> | null;
-  boundHandlers: { [key: number]: any };
-  observer?: Observer;
-  render?: CompiledTemplate;
-  mountedHandlers: { [key: number]: Function };
-}
-
-// If a component does not define explicitely a template
-// key, it needs to find a template with its name (or a parent's).  This is
-// qweb dependant, so we need a place to store this information indexed by
-// qweb instances.
-const TEMPLATE_MAP: { [key: number]: { [name: string]: string } } = {};
-
-//------------------------------------------------------------------------------
-// Widget
-//------------------------------------------------------------------------------
-let nextId = 1;
-
-export class Component<
-  T extends Env,
-  Props extends {},
-  State extends {}
-> extends EventBus {
-  readonly __owl__: Meta<Env, Props>;
-  template?: string;
-
-  get el(): HTMLElement | null {
-    return this.__owl__.vnode ? (<any>this).__owl__.vnode.elm : null;
-  }
-
-  env: T;
-  state?: State;
-  props: Props;
-  refs: {
-    [key: string]: Component<T, any, any> | HTMLElement | undefined;
-  } = {};
-
-  //--------------------------------------------------------------------------
-  // Lifecycle
-  //--------------------------------------------------------------------------
-
-  /**
-   * Creates an instance of Component.
-   *
-   * The root widget of a component tree needs an environment:
-   *
-   * ```javascript
-   *   const root = new RootWidget(env, props);
-   * ```
-   *
-   * Every other widget simply needs a reference to its parent:
-   *
-   * ```javascript
-   *   const child = new SomeWidget(parent, props);
-   * ```
-   *
-   * Note that most of the time, only the root widget needs to be created by
-   * hand.  Other widgets should be created automatically by the framework (with
-   * the t-widget directive in a template)
-   */
-  constructor(parent: Component<T, any, any> | T, props?: Props) {
-    super();
-
-    // is this a good idea?
-    //   Pro: if props is empty, we can create easily a widget
-    //   Con: this is not really safe
-    //   Pro: but creating widget (by a template) is always unsafe anyway
-    this.props = <Props>props || <Props>{};
-    let id: number = nextId++;
-    let p: Component<T, any, any> | null = null;
-    if (parent instanceof Component) {
-      p = parent;
-      this.env = parent.env;
-      parent.__owl__.children[id] = this;
-    } else {
-      this.env = parent;
-    }
-    this.__owl__ = {
-      id: id,
-      vnode: null,
-      isMounted: false,
-      isDestroyed: false,
-      parent: p,
-      children: {},
-      cmap: {},
-      renderId: 1,
-      renderPromise: null,
-      renderProps: props || null,
-      boundHandlers: {},
-      mountedHandlers: {}
-    };
-  }
-
-  /**
-   * willStart is an asynchronous hook that can be implemented to perform some
-   * action before the initial rendering of a component.
-   *
-   * It will be called exactly once before the initial rendering. It is useful
-   * in some cases, for example, to load external assets (such as a JS library)
-   * before the widget is rendered.
-   *
-   * Note that a slow willStart method will slow down the rendering of the user
-   * interface.  Therefore, some effort should be made to make this method as
-   * fast as possible.
-   *
-   * Note: this method should not be called manually.
-   */
-  async willStart() {}
-
-  /**
-   * mounted is a hook that is called each time a component is attached to the
-   * DOM. This is a good place to add some listeners, or to interact with the
-   * DOM, if the component needs to perform some measure for example.
-   *
-   * Note: this method should not be called manually.
-   *
-   * @see willUnmount
-   */
-  mounted() {}
-
-  /**
-   * The willUpdateProps is an asynchronous hook, called just before new props
-   * are set. This is useful if the component needs some asynchronous task
-   * performed, depending on the props (for example, assuming that the props are
-   * some record Id, fetching the record data).
-   *
-   * This hook is not called during the first render (but willStart is called
-   * and performs a similar job).
-   */
-  async willUpdateProps(nextProps: Props) {}
-
-  /**
-   * The willPatch hook is called just before the DOM patching process starts.
-   * It is not called on the initial render.  This is useful to get some
-   * information which are in the DOM.  For example, the current position of the
-   * scrollbar
-   *
-   * The return value of willPatch will be given to the patched function.
-   */
-  willPatch(): any {}
-
-  /**
-   * This hook is called whenever a component did actually update its props,
-   * state or env.
-   *
-   * This method is not called on the initial render. It is useful to interact
-   * with the DOM (for example, through an external library) whenever the
-   * component was updated.
-   *
-   * Updating the widget state in this hook is possible, but not encouraged.
-   * One need to be careful, because updates here will cause rerender, which in
-   * turn will cause other calls to updated. So, we need to be particularly
-   * careful at avoiding endless cycles.
-   *
-   * The snapshot parameter is the result of the call to willPatch.
-   */
-  patched(snapshot: any) {}
-
-  /**
-   * willUnmount is a hook that is called each time just before a component is
-   * unmounted from the DOM. This is a good place to remove some listeners, for
-   * example.
-   *
-   * Note: this method should not be called manually.
-   *
-   * @see mounted
-   */
-  willUnmount() {}
-
-  //--------------------------------------------------------------------------
-  // Public
-  //--------------------------------------------------------------------------
-
-  async mount(target: HTMLElement): Promise<void> {
-    const vnode = await this._prepare();
-    if (this.__owl__.isDestroyed) {
-      // widget was destroyed before we get here...
-      return;
-    }
-    this._patch(vnode);
-    target.appendChild(this.el!);
-
-    if (document.body.contains(target)) {
-      this._callMounted();
-    }
-  }
-
-  _callMounted() {
-    const children = this.__owl__.children;
-    for (let id in children) {
-      const comp = children[id];
-      if (!comp.__owl__.isMounted && this.el!.contains(comp.el)) {
-        comp._callMounted();
-      }
-    }
-    this.__owl__.isMounted = true;
-    for (let key in this.__owl__.mountedHandlers) {
-      this.__owl__.mountedHandlers[key]();
-    }
-    this.mounted();
-  }
-
-  _callWillUnmount() {
-    this.willUnmount();
-    this.__owl__.isMounted = false;
-    const children = this.__owl__.children;
-    for (let id in children) {
-      const comp = children[id];
-      if (comp.__owl__.isMounted) {
-        comp._callWillUnmount();
-      }
-    }
-  }
-
-  unmount() {
-    if (this.__owl__.isMounted) {
-      this._callWillUnmount();
-      this.el!.remove();
-    }
-  }
-
-  async render(force: boolean = false, patchQueue?: any[]): Promise<void> {
-    if (!this.__owl__.isMounted) {
-      return;
-    }
-    const shouldPatch: boolean = !patchQueue;
-    if (shouldPatch) {
-      patchQueue = [];
-    }
-    const renderVDom = this._render(force, patchQueue);
-    const renderId = this.__owl__.renderId;
-    await renderVDom;
-
-    if (
-      shouldPatch &&
-      this.__owl__.isMounted &&
-      renderId === this.__owl__.renderId
-    ) {
-      // we only update the vnode and the actual DOM if no other rendering
-      // occurred between now and when the render method was initially called.
-      for (let i = 0; i < patchQueue!.length; i++) {
-        const patch = patchQueue![i];
-        patch.push(patch[0].willPatch());
-      }
-      for (let i = 0; i < patchQueue!.length; i++) {
-        const patch = patchQueue![i];
-        patch[0]._patch(patch[1]);
-      }
-
-      for (let i = patchQueue!.length - 1; i >= 0; i--) {
-        const patch = patchQueue![i];
-        patch[0].patched(patch[2]);
-      }
-    }
-  }
-
-  destroy() {
-    if (!this.__owl__.isDestroyed) {
-      const el = this.el;
-      this._destroy(this.__owl__.parent);
-      if (el) {
-        el.remove();
-      }
-    }
-  }
-
-  _destroy(parent) {
-    const isMounted = this.__owl__.isMounted;
-    if (isMounted) {
-      this.willUnmount();
-      this.__owl__.isMounted = false;
-    }
-    const children = Object.values(this.__owl__.children);
-    for (let child of children) {
-      child._destroy(this);
-    }
-    if (parent) {
-      let id = this.__owl__.id;
-      delete parent.__owl__.children[id];
-      this.__owl__.parent = null;
-    }
-    this.clear();
-    this.__owl__.isDestroyed = true;
-    delete this.__owl__.vnode;
-  }
-
-  shouldUpdate(nextProps: Props): boolean {
-    return true;
-  }
-
-  /**
-   * This method is the correct way to update the environment of a widget. Doing
-   * this will cause a full rerender of the widget and its children, so this is
-   * an operation that should not be done frequently.
-   *
-   * A good usecase for updating the environment would be to update some mostly
-   * static config keys, such as a boolean to determine if we are in mobile
-   * mode or not.
-   */
-  async updateEnv(nextEnv: Partial<T>): Promise<void> {
-    if (this.__owl__.parent && this.__owl__.parent.env === this.env) {
-      this.env = Object.create(this.env);
-    }
-    Object.assign(this.env, nextEnv);
-    if (this.__owl__.isMounted) {
-      await this.render(true);
-    }
-  }
-
-  set(target: any, key: string | number, value: any) {
-    this.__owl__.observer!.set(target, key, value);
-  }
-
-  //--------------------------------------------------------------------------
-  // Private
-  //--------------------------------------------------------------------------
-
-  async _updateProps(
-    nextProps: Props,
-    forceUpdate: boolean = false,
-    patchQueue?: any[]
-  ): Promise<void> {
-    const shouldUpdate = forceUpdate || this.shouldUpdate(nextProps);
-    if (shouldUpdate) {
-      await this.willUpdateProps(nextProps);
-      this.props = nextProps;
-      await this.render(forceUpdate, patchQueue);
-    }
-  }
-
-  _patch(vnode) {
-    this.__owl__.renderPromise = null;
-    const target = this.__owl__.vnode || document.createElement(vnode.sel!);
-    this.__owl__.vnode = patch(target, vnode);
-  }
-  _prepare(): Promise<VNode> {
-    this.__owl__.renderProps = this.props;
-    this.__owl__.renderPromise = this._prepareAndRender();
-    return this.__owl__.renderPromise;
-  }
-
-  async _prepareAndRender(): Promise<VNode> {
-    await this.willStart();
-    if (this.__owl__.isDestroyed) {
-      return Promise.resolve(h("div"));
-    }
-    const qweb = this.env.qweb;
-    if (!this.template) {
-      let tmap = TEMPLATE_MAP[qweb.id];
-      if (!tmap) {
-        tmap = {};
-        TEMPLATE_MAP[qweb.id] = tmap;
-      }
-      let p = (<any>this).constructor;
-      let name: string = p.name;
-      let template = tmap[name];
-      if (template) {
-        this.template = template;
-      } else {
-        while (
-          (template = p.name) &&
-          !(template in qweb.templates) &&
-          p !== Component
-        ) {
-          p = p.__proto__;
-        }
-        if (p === Component) {
-          this.template = "default";
-        } else {
-          tmap[name] = template;
-          this.template = template;
-        }
-      }
-    }
-    this.__owl__.render = qweb.render.bind(qweb, this.template);
-    this._observeState();
-    return this._render();
-  }
-  async _render(
-    force: boolean = false,
-    patchQueue: any[] = []
-  ): Promise<VNode> {
-    this.__owl__.renderId++;
-    const promises: Promise<void>[] = [];
-    const patch: any[] = [this];
-    if (this.__owl__.isMounted) {
-      patchQueue.push(patch);
-    }
-    if (this.__owl__.observer) {
-      this.__owl__.observer.allowMutations = false;
-    }
-    let vnode = this.__owl__.render!(this, {
-      promises,
-      handlers: this.__owl__.boundHandlers,
-      mountedHandlers: this.__owl__.mountedHandlers,
-      forceUpdate: force,
-      patchQueue
-    });
-    patch.push(vnode);
-    if (this.__owl__.observer) {
-      this.__owl__.observer.allowMutations = true;
-    }
-
-    // this part is critical for the patching process to be done correctly. The
-    // tricky part is that a child widget can be rerendered on its own, which
-    // will update its own vnode representation without the knowledge of the
-    // parent widget.  With this, we make sure that the parent widget will be
-    // able to patch itself properly after
-    vnode.key = this.__owl__.id;
-    this.__owl__.renderProps = this.props;
-    this.__owl__.renderPromise = Promise.all(promises).then(() => vnode);
-    return this.__owl__.renderPromise;
-  }
-
-  /**
-   * Only called by qweb t-widget directive
-   */
-  _mount(vnode: VNode, elm: HTMLElement): VNode {
-    this.__owl__.vnode = patch(elm, vnode);
-    if (
-      this.__owl__.parent!.__owl__.isMounted &&
-      !this.__owl__.isMounted
-    ) {
-      this._callMounted();
-    }
-    return this.__owl__.vnode;
-  }
-
-  __mount() {
-    if (!this.__owl__.isMounted) {
-      this.__owl__.isMounted = true;
-      this.mounted();
-    }
-  }
-
-  _observeState() {
-    if (this.state) {
-      this.__owl__.observer = new Observer();
-      this.__owl__.observer.observe(this.state);
-      this.__owl__.observer.notifyCB = this.render.bind(this);
-    }
-  }
-}

src/component/component.ts

@@ -0,0 +1,29 @@
+import type { ComponentNode } from "./component_node";
+
+// -----------------------------------------------------------------------------
+//  Component Class
+// -----------------------------------------------------------------------------
+
+export class Component {
+  static template: string = "";
+
+  props: any;
+  env: any;
+  __owl__: ComponentNode;
+
+  constructor(props: any, env: any, node: ComponentNode) {
+    this.props = props;
+    this.env = env;
+    this.__owl__ = node;
+  }
+  get el(): HTMLElement | Text | undefined {
+    const node = this.__owl__;
+    return node.bdom ? (node.bdom.firstNode() as any) : undefined;
+  }
+
+  setup() {}
+
+  render(): Promise<void> {
+    return this.__owl__.render();
+  }
+}

src/component/component_node.ts

@@ -0,0 +1,256 @@
+import type { App } from "../app";
+import { BDom, VNode } from "../blockdom";
+import { Component } from "./component";
+import {
+  Fiber,
+  makeChildFiber,
+  makeRootFiber,
+  MountFiber,
+  RootFiber,
+  __internal__destroyed,
+} from "./fibers";
+import { STATUS } from "./status";
+
+export function component(
+  name: string | typeof Component,
+  props: any,
+  key: string,
+  ctx: ComponentNode,
+  parent: any
+): ComponentNode {
+  let node: any = ctx.children[key];
+  let isDynamic = typeof name !== "string";
+
+  if (node && node.status < STATUS.MOUNTED) {
+    node.destroy();
+    node = undefined;
+  }
+  if (isDynamic && node && node.component.constructor !== name) {
+    node = undefined;
+  }
+
+  const parentFiber = ctx.fiber!;
+  if (node) {
+    node.updateAndRender(props, parentFiber);
+  } else {
+    // new component
+    const C = isDynamic ? name : parent.constructor.components[name as any];
+    node = new ComponentNode(C, props, ctx.app);
+    ctx.children[key] = node;
+
+    const fiber = makeChildFiber(node, parentFiber);
+    node.initiateRender(fiber);
+  }
+  return node;
+}
+
+// -----------------------------------------------------------------------------
+//  Component VNode
+// -----------------------------------------------------------------------------
+
+let currentNode: ComponentNode | null = null;
+
+export function getCurrent(): ComponentNode | null {
+  return currentNode;
+}
+
+type LifecycleHook = Function;
+
+export class ComponentNode<T extends typeof Component = any> implements VNode<ComponentNode> {
+  el?: HTMLElement | Text | undefined;
+  handlers: any = null;
+  app: App;
+  fiber: Fiber | null = null;
+  component: InstanceType<T>;
+  bdom: BDom | null = null;
+  status: STATUS = STATUS.NEW;
+
+  renderFn: Function;
+  children: { [key: string]: ComponentNode } = Object.create(null);
+  slots: any = {};
+  refs: any = {};
+
+  willStart: LifecycleHook[] = [];
+  willUpdateProps: LifecycleHook[] = [];
+  willUnmount: LifecycleHook[] = [];
+  mounted: LifecycleHook[] = [];
+  willPatch: LifecycleHook[] = [];
+  patched: LifecycleHook[] = [];
+  destroyed: LifecycleHook[] = [];
+
+  constructor(C: T, props: any, app: App) {
+    currentNode = this;
+    this.app = app;
+    this.component = new C(props, app.env, this) as any;
+    this.renderFn = app.getTemplate(C.template).bind(null, this.component, this);
+    this.component.setup();
+  }
+
+  mountComponent(target: any): Promise<InstanceType<T>> {
+    const fiber = new MountFiber(this, target);
+    this.app.scheduler.addFiber(fiber);
+    this.initiateRender(fiber);
+    return fiber.promise.then(() => this.component);
+  }
+
+  async initiateRender(fiber: Fiber | MountFiber) {
+    if (this.mounted.length) {
+      fiber.root.mounted.push(fiber);
+    }
+    const component = this.component;
+    const prom = Promise.all(this.willStart.map((f) => f.call(component)));
+    await prom;
+    if (this.status === STATUS.NEW && this.fiber === fiber) {
+      this._render(fiber);
+    }
+  }
+
+  async render() {
+    if (this.fiber && !this.fiber.bdom) {
+      return this.fiber.root.promise;
+    }
+    if (!this.bdom && !this.fiber) {
+      // should find a way to return the future mounting promise
+      return;
+    }
+
+    const fiber = makeRootFiber(this);
+    this.app.scheduler.addFiber(fiber);
+    await Promise.resolve();
+    if (this.status === STATUS.DESTROYED) {
+      return;
+    }
+    if (this.fiber === fiber) {
+      this._render(fiber);
+    }
+    return fiber.root.promise;
+  }
+
+  _render(fiber: Fiber | RootFiber) {
+    try {
+      fiber.bdom = this.renderFn();
+    } catch (e) {
+      fiber.root.error = e;
+      this.handleError(fiber);
+    }
+    fiber.root.counter--;
+  }
+
+  handleError(fiber: Fiber) {
+    fiber.node.app.destroy();
+  }
+
+  destroy() {
+    if (this.status === STATUS.MOUNTED) {
+      callWillUnmount(this);
+      this.bdom!.remove();
+    }
+    callDestroyed(this);
+
+    function callWillUnmount(node: ComponentNode) {
+      const component = node.component;
+      for (let cb of node.willUnmount) {
+        cb.call(component);
+      }
+      for (let child of Object.values(node.children)) {
+        if (child.status === STATUS.MOUNTED) {
+          callWillUnmount(child);
+        }
+      }
+    }
+
+    function callDestroyed(node: ComponentNode) {
+      const component = node.component;
+      node.status = STATUS.DESTROYED;
+      for (let child of Object.values(node.children)) {
+        callDestroyed(child);
+      }
+      for (let cb of node.destroyed) {
+        cb.call(component);
+      }
+    }
+  }
+
+  async updateAndRender(props: any, parentFiber: Fiber) {
+    // update
+    const fiber = makeChildFiber(this, parentFiber);
+    if (this.willPatch.length) {
+      parentFiber.root.willPatch.push(fiber);
+    }
+    if (this.patched.length) {
+      parentFiber.root.patched.push(fiber);
+    }
+    const component = this.component;
+    const prom = Promise.all(this.willUpdateProps.map((f) => f.call(component, props)));
+    await prom;
+    if (fiber !== this.fiber) {
+      return;
+    }
+    this.component.props = props;
+    this._render(fiber);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Block DOM methods
+  // ---------------------------------------------------------------------------
+
+  firstNode(): Node | undefined {
+    const bdom = this.bdom;
+    return bdom ? bdom.firstNode() : undefined;
+  }
+
+  mount(parent: HTMLElement, anchor: ChildNode) {
+    const bdom = this.fiber!.bdom!;
+    this.bdom = bdom;
+    bdom.mount(parent, anchor);
+    this.status = STATUS.MOUNTED;
+    this.fiber!.appliedToDom = true;
+    this.fiber = null;
+    if (this.handlers) {
+      for (let i = 0; i < this.handlers.length; i++) {
+        const handler = this.handlers[i];
+        const eventType = handler[0];
+        const el = bdom.el!;
+        el.addEventListener(eventType, (ev: Event) => {
+          const info = this.handlers![i];
+          const [, ctx, method] = info;
+          (ctx.__owl__.component as any)[method](ev);
+        });
+      }
+    }
+  }
+
+  moveBefore(other: ComponentNode | null, afterNode: Node | null) {
+    this.bdom!.moveBefore(other ? other.bdom : null, afterNode);
+  }
+
+  patch() {
+    this.bdom!.patch(this!.fiber!.bdom!, false);
+    this.fiber!.appliedToDom = true;
+    this.fiber = null;
+  }
+
+  beforeRemove() {
+    visitRemovedNodes(this);
+  }
+
+  remove() {
+    this.bdom!.remove();
+  }
+}
+
+function visitRemovedNodes(node: ComponentNode) {
+  if (node.status === STATUS.MOUNTED) {
+    const component = node.component;
+    for (let cb of node.willUnmount) {
+      cb.call(component);
+    }
+  }
+  for (let child of Object.values(node.children)) {
+    visitRemovedNodes(child);
+  }
+  node.status = STATUS.DESTROYED;
+  if (node.destroyed.length) {
+    __internal__destroyed.push(node);
+  }
+}

src/component/fibers.ts

@@ -0,0 +1,185 @@
+import type { BDom } from "../blockdom";
+import { mount } from "../blockdom";
+import type { ComponentNode } from "./component_node";
+import { STATUS } from "./status";
+// import { mountBlock } from "./bdom/block";
+
+export function makeChildFiber(node: ComponentNode, parent: Fiber): Fiber {
+  let current = node.fiber;
+  if (current) {
+    // current is necessarily a rootfiber here
+    let root = parent.root;
+    cancelFibers(root, current.children);
+    current.children = [];
+    current.parent = parent;
+    root.counter++;
+    current.root = root;
+    return current;
+  }
+  return new Fiber(node, parent);
+}
+
+export function makeRootFiber(node: ComponentNode): Fiber {
+  let current = node.fiber;
+  if (current) {
+    let root = current.root;
+    root.counter -= cancelFibers(root, current.children);
+    current.children = [];
+    root.counter++;
+    current.bdom = null;
+    return current;
+  }
+  const fiber = new RootFiber(node);
+  if (node.willPatch.length) {
+    fiber.willPatch.push(fiber);
+  }
+  if (node.patched.length) {
+    fiber.patched.push(fiber);
+  }
+
+  return fiber;
+}
+
+/**
+ * @returns number of not-yet rendered fibers cancelled
+ */
+function cancelFibers(root: any, fibers: Fiber[]): number {
+  let result = 0;
+  for (let fiber of fibers) {
+    fiber.node.fiber = null;
+    fiber.root = root;
+    if (!fiber.bdom) {
+      result++;
+    }
+    result += cancelFibers(root, fiber.children);
+  }
+  return result;
+}
+
+export class Fiber {
+  node: ComponentNode;
+  bdom: BDom | null = null;
+  root: RootFiber;
+  parent: Fiber | null;
+  children: Fiber[] = [];
+  appliedToDom = false;
+
+  constructor(node: ComponentNode, parent: Fiber | null) {
+    this.node = node;
+    node.fiber = this;
+    this.parent = parent;
+    if (parent) {
+      const root = parent.root;
+      root.counter++;
+      this.root = root;
+      parent.children.push(this);
+    } else {
+      this.root = this as any;
+    }
+  }
+}
+
+export class RootFiber extends Fiber {
+  counter: number = 1;
+  error: Error | null = null;
+  resolve: any;
+  promise: Promise<any>;
+  reject: any;
+
+  // only add stuff in this if they have registered some hooks
+  willPatch: Fiber[] = [];
+  patched: Fiber[] = [];
+  mounted: Fiber[] = [];
+
+  constructor(node: ComponentNode) {
+    super(node, null);
+    this.counter = 1;
+
+    this.promise = new Promise((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+
+  complete() {
+    const node = this.node;
+
+    // Step 1: calling all willPatch lifecycle hooks
+    for (let fiber of this.willPatch) {
+      // because of the asynchronous nature of the rendering, some parts of the
+      // UI may have been rendered, then deleted in a followup rendering, and we
+      // do not want to call onWillPatch in that case.
+      let node = fiber.node;
+      if (node.fiber === fiber) {
+        const component = node.component;
+        for (let cb of node.willPatch) {
+          cb.call(component);
+        }
+      }
+    }
+
+    // Step 2: patching the dom
+    node.bdom!.patch(this.bdom!, Object.keys(node.children).length > 0);
+    this.appliedToDom = true;
+
+    // Step 3: calling all destroyed hooks
+    for (let node of __internal__destroyed) {
+      for (let cb of node.destroyed) {
+        cb();
+      }
+    }
+    __internal__destroyed.length = 0;
+
+    // Step 4: calling all mounted lifecycle hooks
+    let current;
+    let mountedFibers = this.mounted;
+    while ((current = mountedFibers.pop())) {
+      if (current.appliedToDom) {
+        for (let cb of current.node.mounted) {
+          cb();
+        }
+      }
+    }
+
+    // Step 5: calling all patched hooks
+    let patchedFibers = this.patched;
+    while ((current = patchedFibers.pop())) {
+      if (current.appliedToDom) {
+        for (let cb of current.node.patched) {
+          cb();
+        }
+      }
+    }
+
+    // unregistering the fiber
+    node.fiber = null;
+  }
+}
+
+export let __internal__destroyed: ComponentNode[] = [];
+
+export class MountFiber extends RootFiber {
+  target: HTMLElement;
+
+  constructor(node: ComponentNode, target: HTMLElement) {
+    super(node);
+    this.target = target;
+  }
+  complete() {
+    const node = this.node;
+    node.bdom = this.bdom;
+    mount(node.bdom!, this.target);
+    node.status = STATUS.MOUNTED;
+    this.appliedToDom = true;
+    let current;
+    let mountedFibers = this.mounted;
+    while ((current = mountedFibers.pop())) {
+      if (current.appliedToDom) {
+        for (let cb of current.node.mounted) {
+          cb();
+        }
+      }
+    }
+    node.fiber = null;
+  }
+}

src/component/handler.ts

@@ -0,0 +1,10 @@
+export function mainEventHandler(data: any, ev: Event) {
+  if (typeof data === "function") {
+    data(ev);
+  } else {
+    const ctx = data[0];
+    const method = data[1];
+    const args = data[2] || [];
+    ctx.__owl__.component[method](...args, ev);
+  }
+}

src/component/scheduler.ts

@@ -0,0 +1,79 @@
+import { Fiber, RootFiber } from "./fibers";
+import { STATUS } from "./status";
+
+// -----------------------------------------------------------------------------
+//  Scheduler
+// -----------------------------------------------------------------------------
+
+export class Scheduler {
+  tasks: Set<RootFiber> = new Set();
+  isRunning: boolean = false;
+  requestAnimationFrame: Window["requestAnimationFrame"];
+
+  constructor(requestAnimationFrame: Window["requestAnimationFrame"]) {
+    this.requestAnimationFrame = requestAnimationFrame;
+  }
+
+  start() {
+    this.isRunning = true;
+    this.scheduleTasks();
+  }
+
+  stop() {
+    this.isRunning = false;
+  }
+
+  addFiber(fiber: Fiber) {
+    this.tasks.add(fiber.root);
+    if (!this.isRunning) {
+      this.start();
+    }
+  }
+
+  /**
+   * Process all current tasks. This only applies to the fibers that are ready.
+   * Other tasks are left unchanged.
+   */
+  flush() {
+    this.tasks.forEach((fiber) => {
+      if (fiber.root !== fiber) {
+        // this is wrong! should be something like
+        // if (this.tasks.has(fiber.root)) {
+        //   // parent rendering has completed
+        //   fiber.resolve();
+        //   this.tasks.delete(fiber);
+        // }
+        this.tasks.delete(fiber);
+        return;
+      }
+      if (fiber.error) {
+        this.tasks.delete(fiber);
+        fiber.reject(fiber.error);
+        return;
+      }
+      if (fiber.node.status === STATUS.DESTROYED) {
+        this.tasks.delete(fiber);
+        return;
+      }
+      if (fiber.counter === 0) {
+        if (!fiber.error) {
+          fiber.complete();
+        }
+        fiber.resolve();
+        this.tasks.delete(fiber);
+      }
+    });
+    if (this.tasks.size === 0) {
+      this.stop();
+    }
+  }
+
+  scheduleTasks() {
+    this.requestAnimationFrame(() => {
+      this.flush();
+      if (this.isRunning) {
+        this.scheduleTasks();
+      }
+    });
+  }
+}

src/component/status.ts

@@ -0,0 +1,24 @@
+import type { Component } from "./component";
+
+// -----------------------------------------------------------------------------
+//  Status
+// -----------------------------------------------------------------------------
+
+export const enum STATUS {
+  NEW,
+  MOUNTED, // is ready, and in DOM. It has a valid el
+  DESTROYED,
+}
+
+type STATUS_DESCR = "new" | "mounted" | "destroyed";
+
+export function status(component: Component): STATUS_DESCR {
+  switch (component.__owl__.status) {
+    case STATUS.NEW:
+      return "new";
+    case STATUS.MOUNTED:
+      return "mounted";
+    case STATUS.DESTROYED:
+      return "destroyed";
+  }
+}

src/event_bus.ts

@@ -1,78 +1,5 @@
-/**
- * We define here a simple event bus: it can
- * - emit events
- * - add/remove listeners.
- *
- * This is a useful pattern of communication in many cases.  For OWL, each
- * components and stores are event buses.
- */
-
-//------------------------------------------------------------------------------
-// Types
-//------------------------------------------------------------------------------
-
-export type Callback = (...args: any[]) => void;
-
-export interface Subscription {
-  owner: any;
-  callback: Callback;
-}
-
-//------------------------------------------------------------------------------
-// EventBus
-//------------------------------------------------------------------------------
-
-export class EventBus {
-  subscriptions: { [eventType: string]: Subscription[] } = {};
-
-  /**
-   * Add a listener for the 'eventType' events.
-   *
-   * Note that the 'owner' of this event can be anything, but will more likely
-   * be a widget or a class. The idea is that the callback will be called with
-   * the proper owner bound.
-   *
-   * Also, the owner should be kind of unique. This will be used to remove the
-   * listener.
-   */
-  on(eventType: string, owner: any, callback: Callback) {
-    if (!callback) {
-      throw new Error("Missing callback");
-    }
-    if (!this.subscriptions[eventType]) {
-      this.subscriptions[eventType] = [];
-    }
-    this.subscriptions[eventType].push({
-      owner,
-      callback
-    });
-  }
-
-  /**
-   * Remove a listener
-   */
-  off(eventType: string, owner: any) {
-    const subs = this.subscriptions[eventType];
-    if (subs) {
-      this.subscriptions[eventType] = subs.filter(s => s.owner !== owner);
-    }
-  }
-
-  /**
-   * Emit an event of type 'eventType'.  Any extra arguments will be passed to
-   * the listeners callback.
-   */
-  trigger(eventType: string, ...args: any[]) {
-    const subs = this.subscriptions[eventType] || [];
-    for (let sub of subs) {
-      sub.callback.call(sub.owner, ...args);
-    }
-  }
-
-  /**
-   * Remove all subscriptions.
-   */
-  clear() {
-    this.subscriptions = {};
+export class EventBus extends EventTarget {
+  trigger(name: string, payload?: any) {
+    this.dispatchEvent(new CustomEvent(name, { detail: payload }));
   }
 }

src/index.ts

@@ -1,21 +1,73 @@
-/**
- * This file is the main file packaged by rollup (see rollup.config.js).  From
- * this file, we export all public owl elements.
- *
- * Note that dynamic values, such as a date or a commit hash are added by rollup
- */
-export { Component } from "./component";
+import {
+  config,
+  createBlock,
+  html,
+  list,
+  mount as blockMount,
+  multi,
+  patch,
+  remove,
+  text,
+  toggler,
+} from "./blockdom";
+import { mainEventHandler } from "./component/handler";
+
+config.shouldNormalizeDom = false;
+config.mainEventHandler = mainEventHandler;
+
+export const blockDom = {
+  config,
+  // bdom entry points
+  mount: blockMount,
+  patch,
+  remove,
+  // bdom block types
+  list,
+  multi,
+  text,
+  toggler,
+  createBlock,
+  html,
+};
+
+// import { makeBlockClass } from "./_old_bdom/element";
+import { App } from "./app";
+import { Component } from "./component/component";
+import { getCurrent } from "./component/component_node";
+// import { getCurrent } from "./b_node";
+
+export { App, Component };
+
+export async function mount<T extends typeof Component>(
+  C: T,
+  target: HTMLElement
+): Promise<InstanceType<T>> {
+  const app = new App(C);
+  return app.mount(target);
+}
+
+export function useComponent(): Component {
+  const current = getCurrent();
+  return current!.component;
+}
+
+export { status } from "./component/status";
+export { Portal } from "./misc/portal";
+export { Memo } from "./misc/memo";
+export { xml } from "./tags";
+export { useState } from "./reactivity";
+export { useRef } from "./refs";
 export { EventBus } from "./event_bus";
-export { Observer } from "./observer";
 
-// we need to import manually the extra directives so they can register
-// themselves in QWeb, otherwise these files will not even be loaded.
-import "./qweb_directives";
-import "./qweb_extensions";
-export { QWeb } from "./qweb_core";
+export {
+  onWillStart,
+  onMounted,
+  onWillUnmount,
+  onWillUpdateProps,
+  onWillPatch,
+  onPatched,
+  onRender,
+  onDestroyed,
+} from "./lifecycle_hooks";
 
-export { connect, Store } from "./store";
-import * as _utils from "./utils";
-
-
-export const utils = _utils;
+export const __info__ = {};

src/lifecycle_hooks.ts

@@ -0,0 +1,49 @@
+import { getCurrent } from "./component/component_node";
+
+// -----------------------------------------------------------------------------
+//  hooks
+// -----------------------------------------------------------------------------
+
+export function onWillStart(fn: () => Promise<void> | void | any) {
+  const node = getCurrent()!;
+  node.willStart.push(fn);
+}
+
+export function onWillUpdateProps(fn: (nextProps: any) => Promise<void> | void | any) {
+  const node = getCurrent()!;
+  node.willUpdateProps.push(fn);
+}
+
+export function onMounted(fn: () => void | any) {
+  const node = getCurrent()!;
+  node.mounted.push(fn);
+}
+
+export function onWillPatch(fn: () => Promise<void> | any | void) {
+  const node = getCurrent()!;
+  node.willPatch.push(fn);
+}
+
+export function onPatched(fn: () => void | any) {
+  const node = getCurrent()!;
+  node.patched.push(fn);
+}
+
+export function onWillUnmount(fn: () => Promise<void> | void | any) {
+  const node = getCurrent()!;
+  node.willUnmount.push(fn);
+}
+
+export function onDestroyed(fn: () => Promise<void> | void | any) {
+  const node = getCurrent()!;
+  node.destroyed.push(fn);
+}
+
+export function onRender(fn: () => void | any) {
+  const node = getCurrent()!;
+  const renderFn = node.renderFn;
+  node.renderFn = () => {
+    fn();
+    return renderFn();
+  };
+}

src/misc/memo.ts

@@ -0,0 +1,47 @@
+import { Component } from "../component/component";
+import type { ComponentNode } from "../component/component_node";
+import { xml } from "../tags";
+import { Fiber } from "../component/fibers";
+
+export class Memo extends Component {
+  static template = xml`<t t-slot="default"/>`;
+
+  constructor(props: any, env: any, node: ComponentNode) {
+    super(props, env, node);
+
+    // prevent patching process conditionally
+    let applyPatch = false;
+    const patchFn = node.patch;
+    node.patch = () => {
+      if (applyPatch) {
+        patchFn.call(node);
+        applyPatch = false;
+      }
+    };
+
+    // check props change, and render/apply patch if it changed
+    let prevProps = props;
+    const updateAndRender = node.updateAndRender;
+    node.updateAndRender = function (props: any, parentFiber: Fiber) {
+      const shouldUpdate = !shallowEqual(prevProps, props);
+      if (shouldUpdate) {
+        prevProps = props;
+        updateAndRender.call(node, props, parentFiber);
+        applyPatch = true;
+      }
+      return Promise.resolve();
+    };
+  }
+}
+
+/**
+ * we assume that each object have the same set of keys
+ */
+function shallowEqual(p1: any, p2: any): boolean {
+  for (let k in p1) {
+    if (p1[k] !== p2[k]) {
+      return false;
+    }
+  }
+  return true;
+}

src/misc/portal.ts

@@ -0,0 +1,65 @@
+import type { ComponentNode } from "../component/component_node";
+import { Component } from "../component/component";
+import { xml } from "../tags";
+import { BDom, text, VNode } from "../blockdom";
+
+const VText: any = text("").constructor;
+
+class VPortal extends VText implements Partial<VNode<VPortal>> {
+  //   selector: string;
+  realBDom: BDom | null;
+  target: HTMLElement | null = null;
+
+  constructor(selector: string, realBDom: BDom) {
+    super("");
+    this.selector = selector;
+    this.realBDom = realBDom;
+  }
+  mount(parent: HTMLElement, anchor: ChildNode) {
+    super.mount(parent, anchor);
+    this.target = document.querySelector(this.selector) as any;
+    if (!this.target) {
+      let el: any = this.el;
+      while (el && el.parentElement instanceof HTMLElement) {
+        el = el.parentElement;
+      }
+      this.target = el && el.querySelector(this.selector);
+      if (!this.target) {
+        throw new Error("invalid portal target");
+      }
+    }
+    this.realBDom!.mount(this.target!, null);
+  }
+
+  beforeRemove() {
+    this.realBDom!.beforeRemove();
+  }
+  remove() {
+    super.remove();
+    this.realBDom!.remove();
+    this.realBDom = null;
+  }
+
+  patch(other: VPortal) {
+    super.patch(other);
+    if (this.realBDom) {
+      this.realBDom.patch(other.realBDom!, true);
+    } else {
+      this.realBDom = other.realBDom;
+      this.realBDom!.mount(this.target!, null);
+    }
+  }
+}
+
+export class Portal extends Component {
+  static template = xml`<t t-slot="default"/>`;
+
+  constructor(props: any, env: any, node: ComponentNode) {
+    super(props, env, node);
+    node._render = function (fiber: any) {
+      const bdom = new VPortal(props.target, this.renderFn());
+      fiber.bdom = bdom;
+      fiber.root.counter--;
+    };
+  }
+}

src/observer.ts

@@ -1,165 +0,0 @@
-/**
- * Owl Observer
- *
- * This code contains the logic that allows Owl to observe and react to state
- * changes.
- *
- * This is a Observer class that can observe any JS values.  The way it works
- * can be summarized thusly:
- * - primitive values are not observed at all
- * - Objects are observed by replacing all their keys with getters/setters
- *   (recursively)
- * - Arrays are observed by replacing their prototype with a customized version,
- *   which wrap some methods to allow the tracking of each state change.
- *
- * Note that this code is inspired by Vue.
- */
-
-//------------------------------------------------------------------------------
-// Modified Array prototype
-//------------------------------------------------------------------------------
-
-// we define here a new modified Array prototype, which basically override all
-// Array methods that change some state to be able to track their changes
-const methodsToPatch = [
-  "push",
-  "pop",
-  "shift",
-  "unshift",
-  "splice",
-  "sort",
-  "reverse"
-];
-const ArrayProto = Array.prototype;
-const ModifiedArrayProto = Object.create(ArrayProto);
-
-for (let method of methodsToPatch) {
-  const initialMethod = ArrayProto[method];
-  ModifiedArrayProto[method] = function(...args) {
-    if (!this.__observer__.allowMutations) {
-      throw new Error(`Array cannot be changed here")`);
-    }
-    this.__observer__.rev++;
-    this.__observer__.notifyChange();
-    this.__owl__.rev++;
-    let parent = this;
-    do {
-      parent.__owl__.deepRev++;
-    } while ((parent = parent.__owl__.parent));
-    let inserted;
-    switch (method) {
-      case "push":
-      case "unshift":
-        inserted = args;
-        break;
-      case "splice":
-        inserted = args.slice(2);
-        break;
-    }
-    if (inserted) {
-      for (let elem of inserted) {
-        this.__observer__.observe(elem, this);
-      }
-    }
-    return initialMethod.call(this, ...args);
-  };
-}
-
-//------------------------------------------------------------------------------
-// Observer
-//------------------------------------------------------------------------------
-export class Observer {
-  rev: number = 1;
-  allowMutations: boolean = true;
-  dirty: boolean = false;
-
-  notifyCB() {}
-  notifyChange() {
-    this.dirty = true;
-    Promise.resolve().then(() => {
-      if (this.dirty) {
-        this.dirty = false;
-        this.notifyCB();
-      }
-    });
-  }
-
-  observe(value: any, parent?: any) {
-    if (value === null) {
-      // fun fact: typeof null === 'object'
-      return;
-    }
-    if (typeof value !== "object") {
-      return;
-    }
-    if ("__owl__" in value) {
-      // already observed
-      value.__owl__.parent = parent;
-      return;
-    }
-    if (Array.isArray(value)) {
-      this._observeArr(value, parent);
-    } else {
-      this._observeObj(value, parent);
-    }
-  }
-
-  set(target: any, key: number | string, value: any) {
-    this.rev++;
-    this._addProp(target, key, value);
-    target.__owl__.rev++;
-    this.notifyChange();
-  }
-
-  _observeObj<T extends { __owl__?: any }>(obj: T, parent?: any) {
-    const keys = Object.keys(obj);
-    obj.__owl__ = { rev: this.rev, deepRev: this.rev, parent };
-    Object.defineProperty(obj, "__owl__", { enumerable: false });
-    for (let key of keys) {
-      this._addProp(obj, key, obj[key]);
-    }
-  }
-
-  _observeArr(arr: Array<any>, parent?: any) {
-    (<any>arr).__owl__ = { rev: this.rev, deepRev: this.rev, parent };
-    Object.defineProperty(arr, "__owl__", { enumerable: false });
-    (<any>arr).__proto__ = Object.create(ModifiedArrayProto);
-    (<any>arr).__proto__.__observer__ = this;
-    for (let i = 0; i < arr.length; i++) {
-      this.observe(arr[i], arr);
-    }
-  }
-
-  _addProp<T extends { __owl__?: any }>(
-    obj: T,
-    key: string | number,
-    value: any
-  ) {
-    var self = this;
-    Object.defineProperty(obj, key, {
-      enumerable: true,
-      get() {
-        return value;
-      },
-      set(newVal) {
-        if (newVal !== value) {
-          self.rev++;
-          if (!self.allowMutations) {
-            throw new Error(
-              `Observed state cannot be changed here! (key: "${key}", val: "${newVal}")`
-            );
-          }
-          value = newVal;
-          self.observe(newVal, obj);
-          obj.__owl__.rev!++;
-          let parent = obj;
-          do {
-            parent.__owl__.deepRev++;
-          } while ((parent = parent.__owl__.parent) && parent !== obj);
-          self.notifyChange();
-        }
-      }
-    });
-    this.observe(value, obj);
-  }
-}

src/qweb/compiler.ts

@@ -0,0 +1,997 @@
+import { BDom } from "../blockdom";
+import { compileExpr, compileExprToArray, interpolate, INTERP_REGEXP } from "./inline_expressions";
+import {
+  AST,
+  ASTComment,
+  ASTComponent,
+  ASTDebug,
+  ASTDomNode,
+  ASTLog,
+  ASTMulti,
+  ASTSlot,
+  ASTTCall,
+  ASTTCallBlock,
+  ASTTEsc,
+  ASTText,
+  ASTTForEach,
+  ASTTif,
+  ASTTKey,
+  ASTTRaw,
+  ASTTSet,
+  ASTType,
+  parse,
+} from "./parser";
+
+export type Template = (context: any, vnode: any, key?: string) => BDom;
+export type TemplateFunction = (blocks: any, utils: any) => Template;
+
+type BlockType = "block" | "text" | "multi" | "list" | "html";
+
+export function compileTemplate(template: string, name?: string): TemplateFunction {
+  const compiler = new QWebCompiler(template, name);
+  return compiler.compile();
+}
+
+// using a non-html document so that <inner/outer>HTML serializes as XML instead
+// of HTML (as we will parse it as xml later)
+const xmlDoc = document.implementation.createDocument(null, null, null);
+
+// -----------------------------------------------------------------------------
+// BlockDescription
+// -----------------------------------------------------------------------------
+
+class BlockDescription {
+  static nextBlockId = 1;
+  static nextDataId = 1;
+
+  varName: string;
+  blockName: string;
+  isRoot: boolean = false;
+  hasDynamicChildren: boolean = false;
+  children: BlockDescription[] = [];
+  data: string[] = [];
+  dom?: Node;
+  currentDom?: Element;
+  childNumber: number = 0;
+  target: CodeTarget;
+  type: BlockType;
+  parentVar: string = "";
+  id: number;
+
+  constructor(target: CodeTarget, type: BlockType) {
+    this.id = BlockDescription.nextBlockId++;
+    this.varName = "b" + this.id;
+    this.blockName = "block" + this.id;
+    this.target = target;
+    this.type = type;
+  }
+
+  insertData(str: string): number {
+    const id = "d" + BlockDescription.nextDataId++;
+    this.target.addLine(`let ${id} = ${str};`);
+    return this.data.push(id) - 1;
+  }
+
+  insert(dom: Node) {
+    if (this.currentDom) {
+      this.currentDom.appendChild(dom);
+    } else {
+      this.dom = dom;
+    }
+  }
+
+  generateExpr(expr: string): string {
+    if (this.type === "block") {
+      const hasChildren = this.children.length;
+      let params = this.data.length ? `[${this.data.join(", ")}]` : hasChildren ? "[]" : "";
+      if (hasChildren) {
+        params += ", [" + this.children.map((c) => c.varName).join(", ") + "]";
+      }
+      return `${this.blockName}(${params})`;
+    } else if (this.type === "list") {
+      return `list(c${this.id})`;
+    }
+    return expr;
+  }
+
+  asXmlString() {
+    // Can't use outerHTML on text/comment nodes
+    // append dom to any element and use innerHTML instead
+    const t = xmlDoc.createElement('t');
+    t.appendChild(this.dom!);
+    return t.innerHTML;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Compiler code
+// -----------------------------------------------------------------------------
+const FNAMEREGEXP = /^[$A-Z_][0-9A-Z_$]*$/i;
+
+interface Context {
+  block: BlockDescription | null;
+  index: number | string;
+  forceNewBlock: boolean;
+  preventRoot?: boolean;
+  isLast?: boolean;
+}
+
+class CodeTarget {
+  name: string;
+  signature: string = "";
+  indentLevel = 0;
+  loopLevel = 0;
+  code: string[] = [];
+  hasRoot = false;
+  hasCache = false;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  addLine(line: string, idx?: number) {
+    const prefix = new Array(this.indentLevel + 2).join("  ");
+    if (idx === undefined) {
+      this.code.push(prefix + line);
+    } else {
+      this.code.splice(idx, 0, prefix + line);
+    }
+  }
+}
+
+export class QWebCompiler {
+  blocks: BlockDescription[] = [];
+  nextId = 1;
+  nextBlockId = 1;
+  shouldProtectScope: boolean = false;
+  shouldDefineAssign: boolean = false;
+  shouldDefineKey0: boolean = false;
+  hasSafeContext: boolean | null = null;
+  hasRef: boolean = false;
+  // hasTCall: boolean = false;
+  isDebug: boolean = false;
+  functions: CodeTarget[] = [];
+  target = new CodeTarget("main");
+  templateName: string;
+  template: string;
+  ast: AST;
+  staticCalls: { id: string; template: string }[] = [];
+
+  constructor(template: string, name?: string) {
+    this.template = template;
+    this.ast = parse(template);
+    // console.warn(this.ast);
+    if (name) {
+      this.templateName = name;
+    } else {
+      if (template.length > 250) {
+        this.templateName = template.slice(0, 250) + "...";
+      } else {
+        this.templateName = template;
+      }
+    }
+  }
+
+  compile(): TemplateFunction {
+    const ast = this.ast;
+    this.isDebug = ast.type === ASTType.TDebug;
+    BlockDescription.nextBlockId = 1;
+    BlockDescription.nextDataId = 1;
+    this.compileAST(ast, { block: null, index: 0, forceNewBlock: false, isLast: true });
+    const code = this.generateCode();
+    // console.warn(code);
+    return new Function("bdom, helpers", code) as TemplateFunction;
+  }
+
+  addLine(line: string) {
+    this.target.addLine(line);
+  }
+
+  generateId(prefix: string = ""): string {
+    return `${prefix}${this.nextId++}`;
+  }
+
+  generateBlockName(): string {
+    return `block${this.blocks.length + 1}`;
+  }
+
+  insertAnchor(block: BlockDescription) {
+    const tag = `block-child-${block.children.length}`;
+    const anchor = xmlDoc.createElement(tag);
+    block.insert(anchor);
+  }
+
+  createBlock(
+    parentBlock: BlockDescription | null,
+    type: BlockType,
+    ctx: Context
+  ): BlockDescription {
+    const hasRoot = this.target.hasRoot;
+    const block = new BlockDescription(this.target, type);
+    if (!hasRoot && !ctx.preventRoot) {
+      this.target.hasRoot = true;
+      block.isRoot = true;
+    }
+    if (parentBlock) {
+      parentBlock.children.push(block);
+      if (parentBlock.type === "list") {
+        block.parentVar = `c${parentBlock.id}`;
+      }
+    }
+    return block;
+  }
+
+  insertBlock(expression: string, block: BlockDescription, ctx: Context): string | null {
+    let id: string | null = null;
+    const blockExpr = block.generateExpr(expression);
+    if (block.parentVar) {
+      this.addLine(
+        `${block.parentVar}[${ctx.index}] = withKey(${blockExpr}, key${this.target.loopLevel});`
+      );
+    } else if (block.isRoot && !ctx.preventRoot) {
+      this.addLine(`return ${blockExpr};`);
+    } else {
+      this.addLine(`let ${block.varName} = ${blockExpr};`);
+    }
+    return id;
+  }
+
+  generateCode(): string {
+    let mainCode = this.target.code;
+    this.target.code = [];
+    this.target.indentLevel = 0;
+    // define blocks and utility functions
+    this.addLine(`let { text, createBlock, list, multi, html, toggler, component } = bdom;`);
+    this.addLine(
+      `let { withDefault, getTemplate, prepareList, withKey, zero, call, callSlot, capture, shallowEqual } = helpers;`
+    );
+    if (this.shouldDefineAssign) {
+      this.addLine(`let assign = Object.assign;`);
+    }
+
+    for (let { id, template } of this.staticCalls) {
+      this.addLine(`const ${id} = getTemplate(${template});`);
+    }
+
+    // define all blocks
+    if (this.blocks.length) {
+      this.addLine(``);
+      for (let block of this.blocks) {
+        if (block.dom) {
+          this.addLine(`let ${block.blockName} = createBlock(\`${block.asXmlString()}\`);`);
+        }
+      }
+    }
+
+    // define all slots
+    for (let fn of this.functions) {
+      this.generateFunctions(fn);
+    }
+
+    // // generate main code
+    this.target.indentLevel = 0;
+    this.addLine(``);
+    this.addLine(`return function template(ctx, node, key = "") {`);
+    if (this.hasRef) {
+      this.addLine(`  const refs = ctx.__owl__.refs;`);
+    }
+    if (this.shouldProtectScope) {
+      this.addLine(`  ctx = Object.create(ctx);`);
+    }
+    if (this.target.hasCache) {
+      this.addLine(`  let cache = ctx.cache || {};`);
+      this.addLine(`  let nextCache = ctx.cache = {};`);
+    }
+    // if (this.shouldDefineKey0) {
+    //   this.addLine(`  let key0;`);
+    // }
+    for (let line of mainCode) {
+      this.addLine(line);
+    }
+    // console.warn(this.target.code.join('\n'))
+    if (!this.target.hasRoot) {
+      throw new Error("missing root block");
+    }
+    this.addLine("}");
+    const code = this.target.code.join("\n");
+
+    if (this.isDebug) {
+      const msg = `[Owl Debug]\n${code}`;
+      console.log(msg);
+    }
+    return code;
+  }
+
+  generateFunctions(fn: CodeTarget) {
+    this.addLine("");
+    this.addLine(`const ${fn.name} = ${fn.signature}`);
+    if (fn.hasCache) {
+      this.addLine(`let cache = ctx.cache || {};`);
+      this.addLine(`let nextCache = ctx.cache = {};`);
+    }
+    for (let line of fn.code) {
+      this.addLine(line);
+    }
+    this.addLine(`}`);
+  }
+
+  captureExpression(expr: string): string {
+    const tokens = compileExprToArray(expr);
+    const mapping = new Map<string, string>();
+    return tokens
+      .map((tok) => {
+        if (tok.varName) {
+          if (!mapping.has(tok.varName)) {
+            const varId = this.generateId("v");
+            mapping.set(tok.varName, varId);
+            this.addLine(`const ${varId} = ${tok.value};`);
+          }
+          tok.value = mapping.get(tok.varName)!;
+        }
+        return tok.value;
+      })
+      .join("");
+  }
+
+  compileAST(ast: AST, ctx: Context) {
+    switch (ast.type) {
+      case ASTType.Comment:
+        this.compileComment(ast, ctx);
+        break;
+      case ASTType.Text:
+        this.compileText(ast, ctx);
+        break;
+      case ASTType.DomNode:
+        this.compileTDomNode(ast, ctx);
+        break;
+      case ASTType.TEsc:
+        this.compileTEsc(ast, ctx);
+        break;
+      case ASTType.TRaw:
+        this.compileTRaw(ast, ctx);
+        break;
+      case ASTType.TIf:
+        this.compileTIf(ast, ctx);
+        break;
+      case ASTType.TForEach:
+        this.compileTForeach(ast, ctx);
+        break;
+      case ASTType.TKey:
+        this.compileTKey(ast, ctx);
+        break;
+      case ASTType.Multi:
+        this.compileMulti(ast, ctx);
+        break;
+      case ASTType.TCall:
+        this.compileTCall(ast, ctx);
+        break;
+      case ASTType.TCallBlock:
+        this.compileTCallBlock(ast, ctx);
+        break;
+      case ASTType.TSet:
+        this.compileTSet(ast, ctx);
+        break;
+      case ASTType.TComponent:
+        this.compileComponent(ast, ctx);
+        break;
+      case ASTType.TDebug:
+        this.compileDebug(ast, ctx);
+        break;
+      case ASTType.TLog:
+        this.compileLog(ast, ctx);
+        break;
+      case ASTType.TSlot:
+        this.compileTSlot(ast, ctx);
+        break;
+    }
+  }
+
+  compileDebug(ast: ASTDebug, ctx: Context) {
+    this.addLine(`debugger;`);
+    if (ast.content) {
+      this.compileAST(ast.content, ctx);
+    }
+  }
+
+  compileLog(ast: ASTLog, ctx: Context) {
+    this.addLine(`console.log(${compileExpr(ast.expr)});`);
+    if (ast.content) {
+      this.compileAST(ast.content, ctx);
+    }
+  }
+  compileComment(ast: ASTComment, ctx: Context) {
+    let { block, forceNewBlock } = ctx;
+    const isNewBlock = !block || forceNewBlock;
+    if (isNewBlock) {
+      block = this.createBlock(block, "block", ctx);
+      this.blocks.push(block);
+    }
+    const text = xmlDoc.createComment(ast.value);
+    block!.insert(text);
+    if (isNewBlock) {
+      this.insertBlock("", block!, ctx);
+    }
+  }
+
+  compileText(ast: ASTText, ctx: Context) {
+    let { block, forceNewBlock } = ctx;
+    if (!block || forceNewBlock) {
+      block = this.createBlock(block, "text", ctx);
+      this.insertBlock(`text(\`${ast.value}\`)`, block, {
+        ...ctx,
+        forceNewBlock: forceNewBlock && !block,
+      });
+    } else {
+      const createFn = ast.type === ASTType.Text ? xmlDoc.createTextNode : xmlDoc.createComment;
+      block.insert(createFn.call(xmlDoc, ast.value));
+    }
+  }
+
+  generateHandlerCode(handler: string, event: string = ""): string {
+    let args: string = "";
+    const name: string = handler.replace(/\(.*\)/, function (_args) {
+      args = _args.slice(1, -1);
+      return "";
+    });
+    const isMethodCall = name.match(FNAMEREGEXP);
+    if (isMethodCall) {
+      let handlerFn: string;
+      if (args) {
+        const argId = this.generateId("arg");
+        this.addLine(`const ${argId} = [${compileExpr(args)}];`);
+        handlerFn = `'${name}', ${argId}`;
+      } else {
+        handlerFn = `'${name}'`;
+      }
+      return `[${event ? `\`${event}\`` + ", " : ""}ctx, ${handlerFn!}]`;
+    } else {
+      let code = this.captureExpression(handler);
+      code = `{const res = (() => { return ${code} })(); if (typeof res === 'function') { res(e) }}`;
+      let handlerFn = `(e) => ${code}`;
+      if (event) {
+        handlerFn = `[\`${event}\`, ${handlerFn}]`;
+      }
+      return handlerFn;
+    }
+  }
+
+  compileTDomNode(ast: ASTDomNode, ctx: Context) {
+    let { block, forceNewBlock } = ctx;
+    const isNewBlock = !block || forceNewBlock;
+    let codeIdx = this.target.code.length;
+    if (isNewBlock) {
+      block = this.createBlock(block, "block", ctx);
+      this.blocks.push(block);
+    }
+
+    // attributes
+    const attrs: { [key: string]: string } = {};
+    for (let key in ast.attrs) {
+      if (key.startsWith("t-attf")) {
+        let expr = interpolate(ast.attrs[key]);
+        const idx = block!.insertData(expr);
+        attrs["block-attribute-" + idx] = key.slice(7);
+        // console.warn('ccc', staticAttrs)
+      } else if (key.startsWith("t-att")) {
+        let expr = compileExpr(ast.attrs[key]);
+        const idx = block!.insertData(expr);
+        if (key === "t-att") {
+          attrs[`block-attributes`] = String(idx);
+        } else {
+          attrs[`block-attribute-${idx}`] = key.slice(6);
+        }
+      } else {
+        attrs[key] = ast.attrs[key];
+      }
+    }
+
+    // event handlers
+    for (let ev in ast.on) {
+      const name = this.generateHandlerCode(ast.on[ev]);
+      const idx = block!.insertData(name);
+      attrs[`block-handler-${idx}`] = ev;
+    }
+
+    // t-ref
+    if (ast.ref) {
+      this.hasRef = true;
+      const isDynamic = INTERP_REGEXP.test(ast.ref);
+      if (isDynamic) {
+        const str = ast.ref.replace(
+          INTERP_REGEXP,
+          (expr) => "${" + this.captureExpression(expr.slice(2, -2)) + "}"
+        );
+        const idx = block!.insertData(`(el) => refs[\`${str}\`] = el`);
+        attrs["block-ref"] = String(idx);
+      } else {
+        const idx = block!.insertData(`(el) => refs[\`${ast.ref}\`] = el`);
+        attrs["block-ref"] = String(idx);
+      }
+    }
+
+    const dom = xmlDoc.createElement(ast.tag);
+    for (const [attr, val] of Object.entries(attrs)) {
+      if (!(attr === "class" && val === "")) {
+        dom.setAttribute(attr, val);
+      }
+    }
+    block!.insert(dom);
+    if (ast.content.length) {
+      const initialDom = block!.currentDom;
+      block!.currentDom = dom;
+      const children = ast.content;
+      for (let i = 0; i < children.length; i++) {
+        const child = ast.content[i];
+        const subCtx: Context = {
+          block: block,
+          index: block!.childNumber,
+          forceNewBlock: false,
+          isLast: ctx.isLast && i === children.length - 1,
+        };
+        this.compileAST(child, subCtx);
+      }
+      block!.currentDom = initialDom;
+    }
+
+    if (isNewBlock) {
+      this.insertBlock(`${block!.blockName}(ddd)`, block!, ctx)!;
+      // may need to rewrite code!
+      if (block!.children.length && block!.hasDynamicChildren) {
+        const code = this.target.code;
+        const children = block!.children.slice();
+        let current = children.shift();
+        for (let i = codeIdx; i < code.length; i++) {
+          if (code[i].trimStart().startsWith(`let ${current!.varName}`)) {
+            code[i] = code[i].replace(`let ${current!.varName}`, current!.varName);
+            current = children.shift();
+            if (!current) break;
+          }
+        }
+        this.target.addLine(`let ${block!.children.map((c) => c.varName)};`, codeIdx);
+      }
+    }
+  }
+
+  compileTEsc(ast: ASTTEsc, ctx: Context) {
+    let { block, forceNewBlock } = ctx;
+    let expr: string;
+    if (ast.expr === "0") {
+      expr = `ctx[zero]`;
+    } else {
+      expr = compileExpr(ast.expr);
+      if (ast.defaultValue) {
+        expr = `withDefault(${expr}, \`${ast.defaultValue}\`)`;
+      }
+    }
+    if (!block || forceNewBlock) {
+      block = this.createBlock(block, "text", ctx);
+      this.insertBlock(`text(${expr})`, block, { ...ctx, forceNewBlock: forceNewBlock && !block });
+    } else {
+      const idx = block.insertData(expr);
+      const text = xmlDoc.createElement(`block-text-${idx}`);
+      block.insert(text);
+    }
+  }
+
+  compileTRaw(ast: ASTTRaw, ctx: Context) {
+    let { block } = ctx;
+    if (block) {
+      this.insertAnchor(block);
+    }
+    block = this.createBlock(block, "html", ctx);
+    let expr = ast.expr === "0" ? "ctx[zero]" : compileExpr(ast.expr);
+    if (ast.body) {
+      const nextId = BlockDescription.nextBlockId;
+      const subCtx: Context = { block: null, index: 0, forceNewBlock: true };
+      this.compileAST({ type: ASTType.Multi, content: ast.body }, subCtx);
+      expr = `withDefault(${expr}, b${nextId})`;
+    }
+    this.insertBlock(`html(${expr})`, block, ctx);
+  }
+
+  compileTIf(ast: ASTTif, ctx: Context, nextNode?: ASTDomNode) {
+    let { block, forceNewBlock, index } = ctx;
+    let currentIndex = index;
+    const codeIdx = this.target.code.length;
+    const isNewBlock = !block || (block.type !== "multi" && forceNewBlock);
+    if (block) {
+      block.hasDynamicChildren = true;
+    }
+    if (!block || (block.type !== "multi" && forceNewBlock)) {
+      block = this.createBlock(block, "multi", ctx);
+    }
+    this.addLine(`if (${compileExpr(ast.condition)}) {`);
+    this.target.indentLevel++;
+    this.insertAnchor(block!);
+    const subCtx: Context = { block: block, index: currentIndex, forceNewBlock: true };
+    this.compileAST(ast.content, subCtx);
+    this.target.indentLevel--;
+    if (ast.tElif) {
+      for (let clause of ast.tElif) {
+        this.addLine(`} else if (${compileExpr(clause.condition)}) {`);
+        this.target.indentLevel++;
+        this.insertAnchor(block);
+        const subCtx: Context = {
+          block: block,
+          index: currentIndex,
+          forceNewBlock: true,
+        };
+        this.compileAST(clause.content, subCtx);
+        this.target.indentLevel--;
+      }
+    }
+    if (ast.tElse) {
+      this.addLine(`} else {`);
+      this.target.indentLevel++;
+      this.insertAnchor(block);
+      const subCtx: Context = {
+        block: block,
+        index: currentIndex,
+        forceNewBlock: true,
+      };
+      this.compileAST(ast.tElse, subCtx);
+      this.target.indentLevel--;
+    }
+    this.addLine("}");
+    if (isNewBlock) {
+      // note: this part is duplicated from end of compiledomnode:
+      if (block!.children.length) {
+        const code = this.target.code;
+        const children = block!.children.slice();
+        let current = children.shift();
+        for (let i = codeIdx; i < code.length; i++) {
+          if (code[i].trimStart().startsWith(`let ${current!.varName}`)) {
+            code[i] = code[i].replace(`let ${current!.varName}`, current!.varName);
+            current = children.shift();
+            if (!current) break;
+          }
+        }
+        this.target.addLine(`let ${block!.children.map((c) => c.varName)};`, codeIdx);
+      }
+
+      // note: this part is duplicated from end of compilemulti:
+      const args = block!.children.map((c) => c.varName).join(", ");
+      this.insertBlock(`multi([${args}])`, block!, ctx)!;
+    }
+  }
+
+  compileTForeach(ast: ASTTForEach, ctx: Context) {
+    let { block } = ctx;
+    if (block) {
+      this.insertAnchor(block);
+    }
+    block = this.createBlock(block, "list", ctx);
+    this.target.loopLevel++;
+    const loopVar = `i${this.target.loopLevel}`;
+    this.addLine(`ctx = Object.create(ctx);`);
+    // const cId = this.generateId();
+    const vals = `v${block.id}`;
+    const keys = `k${block.id}`;
+    const l = `l${block.id}`;
+    const c = `c${block.id}`;
+    this.addLine(
+      `const [${keys}, ${vals}, ${l}, ${c}] = prepareList(${compileExpr(ast.collection)});`
+    );
+    this.addLine(`for (let ${loopVar} = 0; ${loopVar} < ${l}; ${loopVar}++) {`);
+    this.target.indentLevel++;
+    this.addLine(`ctx[\`${ast.elem}\`] = ${vals}[${loopVar}];`);
+    if (!ast.hasNoFirst) {
+      this.addLine(`ctx[\`${ast.elem}_first\`] = ${loopVar} === 0;`);
+    }
+    if (!ast.hasNoLast) {
+      this.addLine(`ctx[\`${ast.elem}_last\`] = ${loopVar} === ${vals}.length - 1;`);
+    }
+    if (!ast.hasNoIndex) {
+      this.addLine(`ctx[\`${ast.elem}_index\`] = ${loopVar};`);
+    }
+    if (!ast.hasNoValue) {
+      this.addLine(`ctx[\`${ast.elem}_value\`] = ${keys}[${loopVar}];`);
+    }
+    this.addLine(`let key${this.target.loopLevel} = ${ast.key ? compileExpr(ast.key) : loopVar};`);
+    let id: string;
+    if (ast.memo) {
+      this.target.hasCache = true;
+      this.shouldDefineAssign = true;
+      id = this.generateId();
+      this.addLine(`let memo${id} = ${compileExpr(ast.memo)}`);
+      this.addLine(`let vnode${id} = cache[key${this.target.loopLevel}];`);
+      this.addLine(`if (vnode${id}) {`);
+      this.target.indentLevel++;
+      this.addLine(`if (shallowEqual(vnode${id}.memo, memo${id})) {`);
+      this.target.indentLevel++;
+      this.addLine(`${c}[${loopVar}] = vnode${id};`);
+      this.addLine(`nextCache[key${this.target.loopLevel}] = vnode${id};`);
+      this.addLine(`continue;`);
+      this.target.indentLevel--;
+      this.addLine("}");
+      this.target.indentLevel--;
+      this.addLine("}");
+    }
+
+    const subCtx: Context = {
+      block: block, //collectionBlock,
+      index: loopVar,
+      forceNewBlock: true,
+    };
+    this.compileAST(ast.body, subCtx);
+    if (!ast.key) {
+      console.warn(
+        `"Directive t-foreach should always be used with a t-key! (in template: '${this.templateName}')"`
+      );
+    }
+    if (ast.memo) {
+      this.addLine(
+        `nextCache[key${this.target.loopLevel}] = assign(${c}[${loopVar}], {memo: memo${id!}});`
+      );
+    }
+    this.target.indentLevel--;
+    this.target.loopLevel--;
+    this.addLine(`}`);
+    if (!ctx.isLast) {
+      this.addLine(`ctx = ctx.__proto__;`);
+    }
+    this.insertBlock("l", block, ctx);
+  }
+
+  compileTKey(ast: ASTTKey, ctx: Context) {
+    this.compileAST(ast.content, ctx);
+  }
+
+  compileMulti(ast: ASTMulti, ctx: Context) {
+    let { block, forceNewBlock } = ctx;
+    const isNewBlock = !block || forceNewBlock;
+    let codeIdx = this.target.code.length;
+    if (isNewBlock) {
+      const n = ast.content.filter((c) => c.type !== ASTType.TSet).length;
+      if (n <= 1) {
+        for (let child of ast.content) {
+          this.compileAST(child, ctx);
+        }
+        return;
+      }
+      block = this.createBlock(block, "multi", ctx);
+    }
+    let index = 0;
+    for (let i = 0, l = ast.content.length; i < l; i++) {
+      const child = ast.content[i];
+      const isTSet = child.type === ASTType.TSet;
+      const subCtx: Context = {
+        block: block,
+        index: index,
+        forceNewBlock: !isTSet,
+        preventRoot: ctx.preventRoot,
+        isLast: ctx.isLast && i === l - 1,
+      };
+      this.compileAST(child, subCtx);
+      if (!isTSet) {
+        index++;
+      }
+    }
+    if (isNewBlock) {
+      if (block!.hasDynamicChildren) {
+        if (block!.children.length) {
+          const code = this.target.code;
+          const children = block!.children.slice();
+          let current = children.shift();
+          for (let i = codeIdx; i < code.length; i++) {
+            if (code[i].trimStart().startsWith(`let ${current!.varName}`)) {
+              code[i] = code[i].replace(`let ${current!.varName}`, current!.varName);
+              current = children.shift();
+              if (!current) break;
+            }
+          }
+          this.target.addLine(`let ${block!.children.map((c) => c.varName)};`, codeIdx);
+        }
+      }
+
+      const args = block!.children.map((c) => c.varName).join(", ");
+      this.insertBlock(`multi([${args}])`, block!, ctx)!;
+    }
+  }
+
+  compileTCall(ast: ASTTCall, ctx: Context) {
+    let { block, forceNewBlock } = ctx;
+    // this.hasTCall = true;
+    if (ast.body) {
+      this.addLine(`ctx = Object.create(ctx);`);
+      const nextId = BlockDescription.nextBlockId;
+      const subCtx: Context = { block: null, index: 0, forceNewBlock: true, preventRoot: true };
+      this.compileAST({ type: ASTType.Multi, content: ast.body }, subCtx);
+      if (nextId !== BlockDescription.nextBlockId) {
+        this.addLine(`ctx[zero] = b${nextId};`);
+      }
+    }
+    const isDynamic = INTERP_REGEXP.test(ast.name);
+    const subTemplate = isDynamic ? interpolate(ast.name) : "`" + ast.name + "`";
+    if (block) {
+      if (!forceNewBlock) {
+        this.insertAnchor(block);
+      }
+    }
+    const key = `key + \`${this.generateComponentKey()}\``;
+    if (isDynamic) {
+      const templateVar = this.generateId("template");
+      this.addLine(`const ${templateVar} = ${subTemplate};`);
+      block = this.createBlock(block, "multi", ctx);
+      this.insertBlock(`call(${templateVar}, ctx, node, ${key})`, block!, {
+        ...ctx,
+        forceNewBlock: !block,
+      });
+    } else {
+      const id = this.generateId(`callTemplate_`);
+      this.staticCalls.push({ id, template: subTemplate });
+      // console.warn('coucoup', this.target.hasRoot)
+      block = this.createBlock(block, "multi", ctx);
+      this.insertBlock(`${id}(ctx, node, ${key})`, block!, { ...ctx, forceNewBlock: !block });
+    }
+    if (ast.body && !ctx.isLast) {
+      this.addLine(`ctx = ctx.__proto__;`);
+    }
+  }
+
+  compileTCallBlock(ast: ASTTCallBlock, ctx: Context) {
+    let { block, forceNewBlock } = ctx;
+    if (block) {
+      if (!forceNewBlock) {
+        this.insertAnchor(block);
+      }
+    }
+    block = this.createBlock(block, "multi", ctx);
+    this.insertBlock(compileExpr(ast.name), block, { ...ctx, forceNewBlock: !block });
+  }
+
+  compileTSet(ast: ASTTSet, ctx: Context) {
+    this.shouldProtectScope = true;
+    const expr = ast.value ? compileExpr(ast.value || "") : "null";
+    if (ast.body) {
+      const subCtx: Context = { block: null, index: 0, forceNewBlock: true };
+      const nextId = `b${BlockDescription.nextBlockId}`;
+      this.compileAST({ type: ASTType.Multi, content: ast.body }, subCtx);
+      const value = ast.value ? (nextId ? `withDefault(${expr}, ${nextId})` : expr) : nextId;
+      this.addLine(`ctx[\`${ast.name}\`] = ${value};`);
+    } else {
+      let value: string;
+      if (ast.defaultValue) {
+        if (ast.value) {
+          value = `withDefault(${expr}, \`${ast.defaultValue}\`)`;
+        } else {
+          value = `\`${ast.defaultValue}\``;
+        }
+      } else {
+        value = expr;
+      }
+      this.addLine(`ctx[\`${ast.name}\`] = ${value};`);
+    }
+  }
+
+  generateComponentKey() {
+    const parts = [this.generateId("__")];
+    for (let i = 0; i < this.target.loopLevel; i++) {
+      parts.push(`\${key${i + 1}}`);
+    }
+    return parts.join("__");
+  }
+
+  compileComponent(ast: ASTComponent, ctx: Context) {
+    let { block } = ctx;
+    let extraArgs: { [key: string]: string } = {};
+
+    // props
+    const props: string[] = [];
+    for (let p in ast.props) {
+      props.push(`${p}: ${compileExpr(ast.props[p]) || undefined}`);
+    }
+    const propString = `{${props.join(",")}}`;
+
+    // cmap key
+    const key = this.generateComponentKey();
+    let expr: string;
+    if (ast.isDynamic) {
+      expr = this.generateId("Comp");
+      this.addLine(`let ${expr} = ${compileExpr(ast.name)};`);
+    } else {
+      expr = `\`${ast.name}\``;
+    }
+    let blockArgs = `${expr}, ${propString}, key + \`${key}\`, node, ctx`;
+
+    // slots
+    const hasSlot = !!Object.keys(ast.slots).length;
+    let slotDef: string;
+    if (hasSlot) {
+      if (this.hasSafeContext === null) {
+        this.hasSafeContext = !this.template.includes("t-set") && !this.template.includes("t-call");
+      }
+      let ctxStr = "ctx";
+      if (this.target.loopLevel || !this.hasSafeContext) {
+        ctxStr = this.generateId("ctx");
+        this.addLine(`const ${ctxStr} = capture(ctx);`);
+      }
+      let slotStr: string[] = [];
+      const initialTarget = this.target;
+      for (let slotName in ast.slots) {
+        let name = this.generateId("slot");
+        const slot = new CodeTarget(name);
+        slot.signature = "ctx => (node, key) => {";
+        this.functions.push(slot);
+        this.target = slot;
+        const subCtx: Context = { block: null, index: 0, forceNewBlock: true };
+        this.compileAST(ast.slots[slotName], subCtx);
+        if (this.hasRef) {
+          slot.signature = "ctx => node => {";
+          slot.code.unshift(`  const refs = ctx.__owl__.refs`);
+          slotStr.push(`'${slotName}': ${name}(${ctxStr})`);
+        } else {
+          slotStr.push(`'${slotName}': ${name}(${ctxStr})`);
+        }
+      }
+      this.target = initialTarget;
+      slotDef = `{${slotStr.join(", ")}}`;
+      extraArgs.slots = slotDef;
+    }
+
+    // handlers
+    const hasHandlers = Object.keys(ast.handlers).length;
+    if (hasHandlers) {
+      const vars = Object.keys(ast.handlers).map((ev) => {
+        let id = this.generateId("h");
+        this.addLine(`let ${id} = ${this.generateHandlerCode(ast.handlers[ev], ev)};`);
+        return id;
+      });
+      extraArgs.handlers = `[${vars}]`;
+    }
+
+    if (block && ctx.forceNewBlock === false) {
+      // todo: check the forcenewblock condition
+      this.insertAnchor(block);
+    }
+    let blockExpr = `component(${blockArgs})`;
+    if (Object.keys(extraArgs).length) {
+      this.shouldDefineAssign = true;
+      const content = Object.keys(extraArgs).map((k) => `${k}: ${extraArgs[k]}`);
+      blockExpr = `assign(${blockExpr}, {${content.join(", ")}})`;
+    }
+    if (ast.isDynamic) {
+      blockExpr = `toggler(${expr}, ${blockExpr})`;
+    }
+    block = this.createBlock(block, "multi", ctx);
+    this.insertBlock(blockExpr, block, ctx);
+  }
+
+  compileTSlot(ast: ASTSlot, ctx: Context) {
+    let { block } = ctx;
+    let blockString: string;
+    let slotName;
+    let dynamic = false;
+    if (ast.name.match(INTERP_REGEXP)) {
+      dynamic = true;
+      slotName = interpolate(ast.name);
+    } else {
+      slotName = "'" + ast.name + "'";
+    }
+    if (ast.defaultContent) {
+      let name = this.generateId("defaultSlot");
+      const slot = new CodeTarget(name);
+      slot.signature = "ctx => {";
+      this.functions.push(slot);
+      const initialTarget = this.target;
+      const subCtx: Context = { block: null, index: 0, forceNewBlock: true };
+      this.target = slot;
+      this.compileAST(ast.defaultContent, subCtx);
+      this.target = initialTarget;
+      blockString = `callSlot(ctx, node, key, ${slotName}, ${name}, ${dynamic})`;
+    } else {
+      if (dynamic) {
+        let name = this.generateId("slot");
+        this.addLine(`const ${name} = ${slotName};`);
+        blockString = `toggler(${name}, callSlot(ctx, node, key, ${name}))`;
+      } else {
+        blockString = `callSlot(ctx, node, key, ${slotName})`;
+      }
+    }
+    if (block) {
+      this.insertAnchor(block);
+    }
+    block = this.createBlock(block, "multi", ctx);
+    this.insertBlock(blockString, block, { ...ctx, forceNewBlock: false });
+  }
+}

src/qweb/inline_expressions.ts

@@ -0,0 +1,348 @@
+/**
+ * Owl QWeb Expression Parser
+ *
+ * Owl needs in various contexts to be able to understand the structure of a
+ * string representing a javascript expression.  The usual goal is to be able
+ * to rewrite some variables.  For example, if a template has
+ *
+ *  ```xml
+ *  <t t-if="computeSomething({val: state.val})">...</t>
+ * ```
+ *
+ * this needs to be translated in something like this:
+ *
+ * ```js
+ *   if (context["computeSomething"]({val: context["state"].val})) { ... }
+ * ```
+ *
+ * This file contains the implementation of an extremely naive tokenizer/parser
+ * and evaluator for javascript expressions.  The supported grammar is basically
+ * only expressive enough to understand the shape of objects, of arrays, and
+ * various operators.
+ */
+
+//------------------------------------------------------------------------------
+// Misc types, constants and helpers
+//------------------------------------------------------------------------------
+
+const RESERVED_WORDS =
+  "true,false,NaN,null,undefined,debugger,console,window,in,instanceof,new,function,return,this,eval,void,Math,RegExp,Array,Object,Date".split(
+    ","
+  );
+
+const WORD_REPLACEMENT: { [key: string]: string } = Object.assign(Object.create(null), {
+  and: "&&",
+  or: "||",
+  gt: ">",
+  gte: ">=",
+  lt: "<",
+  lte: "<=",
+});
+
+export interface QWebVar {
+  id: string; // foo
+  expr: string; // scope.foo (local variables => only foo)
+  value?: string; // 1 + 3
+  hasBody?: boolean;
+}
+
+//------------------------------------------------------------------------------
+// Tokenizer
+//------------------------------------------------------------------------------
+type TKind =
+  | "LEFT_BRACE"
+  | "RIGHT_BRACE"
+  | "LEFT_BRACKET"
+  | "RIGHT_BRACKET"
+  | "LEFT_PAREN"
+  | "RIGHT_PAREN"
+  | "COMMA"
+  | "VALUE"
+  | "TEMPLATE_STRING"
+  | "SYMBOL"
+  | "OPERATOR"
+  | "COLON";
+
+interface Token {
+  type: TKind;
+  value: string;
+  originalValue?: string;
+  size?: number;
+  varName?: string;
+  replace?: Function;
+}
+
+const STATIC_TOKEN_MAP: { [key: string]: TKind } = Object.assign(Object.create(null), {
+  "{": "LEFT_BRACE",
+  "}": "RIGHT_BRACE",
+  "[": "LEFT_BRACKET",
+  "]": "RIGHT_BRACKET",
+  ":": "COLON",
+  ",": "COMMA",
+  "(": "LEFT_PAREN",
+  ")": "RIGHT_PAREN",
+});
+
+// note that the space after typeof is relevant. It makes sure that the formatted
+// expression has a space after typeof
+const OPERATORS = "...,.,===,==,+,!==,!=,!,||,&&,>=,>,<=,<,?,-,*,/,%,typeof ,=>,=,;,in ".split(",");
+
+type Tokenizer = (expr: string) => Token | false;
+
+let tokenizeString: Tokenizer = function (expr) {
+  let s = expr[0];
+  let start = s;
+  if (s !== "'" && s !== '"' && s !== "`") {
+    return false;
+  }
+  let i = 1;
+  let cur;
+  while (expr[i] && expr[i] !== start) {
+    cur = expr[i];
+    s += cur;
+    if (cur === "\\") {
+      i++;
+      cur = expr[i];
+      if (!cur) {
+        throw new Error("Invalid expression");
+      }
+      s += cur;
+    }
+    i++;
+  }
+  if (expr[i] !== start) {
+    throw new Error("Invalid expression");
+  }
+  s += start;
+  if (start === "`") {
+    return {
+      type: "TEMPLATE_STRING",
+      value: s,
+      replace(replacer: any) {
+        return s.replace(/\$\{(.*?)\}/g, (match, group) => {
+          return "${" + replacer(group) + "}";
+        });
+      },
+    };
+  }
+  return { type: "VALUE", value: s };
+};
+
+let tokenizeNumber: Tokenizer = function (expr) {
+  let s = expr[0];
+  if (s && s.match(/[0-9]/)) {
+    let i = 1;
+    while (expr[i] && expr[i].match(/[0-9]|\./)) {
+      s += expr[i];
+      i++;
+    }
+    return { type: "VALUE", value: s };
+  } else {
+    return false;
+  }
+};
+
+let tokenizeSymbol: Tokenizer = function (expr) {
+  let s = expr[0];
+  if (s && s.match(/[a-zA-Z_\$]/)) {
+    let i = 1;
+    while (expr[i] && expr[i].match(/\w/)) {
+      s += expr[i];
+      i++;
+    }
+    if (s in WORD_REPLACEMENT) {
+      return { type: "OPERATOR", value: WORD_REPLACEMENT[s], size: s.length };
+    }
+    return { type: "SYMBOL", value: s };
+  } else {
+    return false;
+  }
+};
+
+const tokenizeStatic: Tokenizer = function (expr) {
+  const char = expr[0];
+  if (char && char in STATIC_TOKEN_MAP) {
+    return { type: STATIC_TOKEN_MAP[char], value: char };
+  }
+  return false;
+};
+
+const tokenizeOperator: Tokenizer = function (expr) {
+  for (let op of OPERATORS) {
+    if (expr.startsWith(op)) {
+      return { type: "OPERATOR", value: op };
+    }
+  }
+  return false;
+};
+
+const TOKENIZERS = [
+  tokenizeString,
+  tokenizeNumber,
+  tokenizeOperator,
+  tokenizeSymbol,
+  tokenizeStatic,
+];
+
+/**
+ * Convert a javascript expression (as a string) into a list of tokens. For
+ * example: `tokenize("1 + b")` will return:
+ * ```js
+ *  [
+ *   {type: "VALUE", value: "1"},
+ *   {type: "OPERATOR", value: "+"},
+ *   {type: "SYMBOL", value: "b"}
+ * ]
+ * ```
+ */
+export function tokenize(expr: string): Token[] {
+  const result: Token[] = [];
+  let token: boolean | Token = true;
+
+  while (token) {
+    expr = expr.trim();
+    if (expr) {
+      for (let tokenizer of TOKENIZERS) {
+        token = tokenizer(expr);
+        if (token) {
+          result.push(token);
+          expr = expr.slice(token.size || token.value.length);
+          break;
+        }
+      }
+    } else {
+      token = false;
+    }
+  }
+  if (expr.length) {
+    throw new Error(`Tokenizer error: could not tokenize "${expr}"`);
+  }
+  return result;
+}
+
+//------------------------------------------------------------------------------
+// Expression "evaluator"
+//------------------------------------------------------------------------------
+
+const isLeftSeparator = (token: Token) =>
+  token && (token.type === "LEFT_BRACE" || token.type === "COMMA");
+const isRightSeparator = (token: Token) =>
+  token && (token.type === "RIGHT_BRACE" || token.type === "COMMA");
+
+/**
+ * This is the main function exported by this file. This is the code that will
+ * process an expression (given as a string) and returns another expression with
+ * proper lookups in the context.
+ *
+ * Usually, this kind of code would be very simple to do if we had an AST (so,
+ * if we had a javascript parser), since then, we would only need to find the
+ * variables and replace them.  However, a parser is more complicated, and there
+ * are no standard builtin parser API.
+ *
+ * Since this method is applied to simple javasript expressions, and the work to
+ * be done is actually quite simple, we actually can get away with not using a
+ * parser, which helps with the code size.
+ *
+ * Here is the heuristic used by this method to determine if a token is a
+ * variable:
+ * - by default, all symbols are considered a variable
+ * - unless the previous token is a dot (in that case, this is a property: `a.b`)
+ * - or if the previous token is a left brace or a comma, and the next token is
+ *   a colon (in that case, this is an object key: `{a: b}`)
+ *
+ * Some specific code is also required to support arrow functions. If we detect
+ * the arrow operator, then we add the current (or some previous tokens) token to
+ * the list of variables so it does not get replaced by a lookup in the context
+ */
+export function compileExprToArray(expr: string): Token[] {
+  const localVars = new Set<string>();
+  const tokens = tokenize(expr);
+  let i = 0;
+  let stack = []; // to track last opening [ or {
+
+  while (i < tokens.length) {
+    let token = tokens[i];
+    let prevToken = tokens[i - 1];
+    let nextToken = tokens[i + 1];
+    let groupType = stack[stack.length - 1];
+
+    switch (token.type) {
+      case "LEFT_BRACE":
+      case "LEFT_BRACKET":
+        stack.push(token.type);
+        break;
+      case "RIGHT_BRACE":
+      case "RIGHT_BRACKET":
+        stack.pop();
+    }
+
+    let isVar = token.type === "SYMBOL" && !RESERVED_WORDS.includes(token.value);
+    if (token.type === "SYMBOL" && !RESERVED_WORDS.includes(token.value)) {
+      if (prevToken) {
+        // normalize missing tokens: {a} should be equivalent to {a:a}
+        if (
+          groupType === "LEFT_BRACE" &&
+          isLeftSeparator(prevToken) &&
+          isRightSeparator(nextToken)
+        ) {
+          tokens.splice(i + 1, 0, { type: "COLON", value: ":" }, { ...token });
+          nextToken = tokens[i + 1];
+        }
+
+        if (prevToken.type === "OPERATOR" && prevToken.value === ".") {
+          isVar = false;
+        } else if (prevToken.type === "LEFT_BRACE" || prevToken.type === "COMMA") {
+          if (nextToken && nextToken.type === "COLON") {
+            isVar = false;
+          }
+        }
+      }
+    }
+    if (token.type === "TEMPLATE_STRING") {
+      token.value = token.replace!((expr: any) => compileExpr(expr));
+    }
+    if (nextToken && nextToken.type === "OPERATOR" && nextToken.value === "=>") {
+      if (token.type === "RIGHT_PAREN") {
+        let j = i - 1;
+        while (j > 0 && tokens[j].type !== "LEFT_PAREN") {
+          if (tokens[j].type === "SYMBOL" && tokens[j].originalValue) {
+            tokens[j].value = tokens[j].originalValue!;
+            localVars.add(tokens[j].value); //] = { id: tokens[j].value, expr: tokens[j].value };
+          }
+          j--;
+        }
+      } else {
+        localVars.add(token.value); //] = { id: token.value, expr: token.value };
+      }
+    }
+
+    if (isVar) {
+      token.varName = token.value;
+      if (!localVars.has(token.value)) {
+        token.originalValue = token.value;
+        token.value = `ctx['${token.value}']`;
+      }
+    }
+    i++;
+  }
+  return tokens;
+}
+
+export function compileExpr(expr: string): string {
+  return compileExprToArray(expr)
+    .map((t) => t.value)
+    .join("");
+}
+
+export const INTERP_REGEXP = /\{\{.*?\}\}/g;
+const INTERP_GROUP_REGEXP = /\{\{.*?\}\}/g;
+
+export function interpolate(s: string): string {
+  let matches = s.match(INTERP_REGEXP);
+  if (matches && matches[0].length === s.length) {
+    return `(${compileExpr(s.slice(2, -2))})`;
+  }
+
+  let r = s.replace(INTERP_GROUP_REGEXP, (s) => "${" + compileExpr(s.slice(2, -2)) + "}");
+  return "`" + r + "`";
+}

src/qweb/parser.ts

@@ -0,0 +1,798 @@
+// -----------------------------------------------------------------------------
+// AST Type definition
+// -----------------------------------------------------------------------------
+
+export const enum ASTType {
+  Text,
+  Comment,
+  DomNode,
+  Multi,
+  TEsc,
+  TIf,
+  TSet,
+  TCall,
+  TRaw,
+  TForEach,
+  TKey,
+  TComponent,
+  TDebug,
+  TLog,
+  TSlot,
+  TCallBlock,
+}
+
+export interface ASTText {
+  type: ASTType.Text;
+  value: string;
+}
+
+export interface ASTComment {
+  type: ASTType.Comment;
+  value: string;
+}
+
+export interface ASTDomNode {
+  type: ASTType.DomNode;
+  tag: string;
+  attrs: { [key: string]: string };
+  content: AST[];
+  ref: string | null;
+  on: { [key: string]: string };
+}
+
+export interface ASTMulti {
+  type: ASTType.Multi;
+  content: AST[];
+}
+
+export interface ASTTEsc {
+  type: ASTType.TEsc;
+  expr: string;
+  defaultValue: string;
+}
+
+export interface ASTTRaw {
+  type: ASTType.TRaw;
+  expr: string;
+  body: AST[] | null;
+}
+
+export interface ASTTif {
+  type: ASTType.TIf;
+  condition: string;
+  content: AST;
+  tElif: { condition: string; content: AST }[] | null;
+  tElse: AST | null;
+}
+
+export interface ASTTSet {
+  type: ASTType.TSet;
+  name: string;
+  value: string | null; // value defined in attribute
+  defaultValue: string | null; // value defined in body, if text
+  body: AST[] | null; // content of body if not text
+}
+
+export interface ASTTForEach {
+  type: ASTType.TForEach;
+  collection: string;
+  elem: string;
+  key: string | null;
+  body: AST;
+  memo: string;
+  isOnlyChild: boolean;
+  hasNoComponent: boolean;
+  hasNoFirst: boolean;
+  hasNoLast: boolean;
+  hasNoIndex: boolean;
+  hasNoValue: boolean;
+}
+
+export interface ASTTKey {
+  type: ASTType.TKey;
+  expr: string;
+  content: AST;
+}
+
+export interface ASTTCall {
+  type: ASTType.TCall;
+  name: string;
+  body: AST[] | null;
+}
+
+export interface ASTComponent {
+  type: ASTType.TComponent;
+  name: string;
+  isDynamic: boolean;
+  props: { [name: string]: string };
+  handlers: { [event: string]: string };
+  slots: { [name: string]: AST };
+}
+
+export interface ASTSlot {
+  type: ASTType.TSlot;
+  name: string;
+  defaultContent: AST | null;
+}
+
+export interface ASTTCallBlock {
+  type: ASTType.TCallBlock;
+  name: string;
+}
+
+export interface ASTDebug {
+  type: ASTType.TDebug;
+  content: AST | null;
+}
+
+export interface ASTLog {
+  type: ASTType.TLog;
+  expr: string;
+  content: AST | null;
+}
+
+export type AST =
+  | ASTText
+  | ASTComment
+  | ASTDomNode
+  | ASTMulti
+  | ASTTEsc
+  | ASTTif
+  | ASTTSet
+  | ASTTCall
+  | ASTTRaw
+  | ASTTForEach
+  | ASTTKey
+  | ASTComponent
+  | ASTSlot
+  | ASTTCallBlock
+  | ASTLog
+  | ASTDebug;
+
+// -----------------------------------------------------------------------------
+// Parser
+// -----------------------------------------------------------------------------
+interface ParsingContext {
+  inPreTag: boolean;
+}
+
+export function parse(xml: string): AST {
+  const template = `<t>${xml}</t>`;
+  const doc = parseXML(template);
+  const ctx = { inPreTag: false };
+  const ast = parseNode(doc.firstChild!, ctx);
+  if (!ast) {
+    return { type: ASTType.Text, value: "" };
+  }
+  return ast;
+}
+
+function parseNode(node: ChildNode, ctx: ParsingContext): AST | null {
+  if (!(node instanceof Element)) {
+    return parseTextCommentNode(node, ctx);
+  }
+  return (
+    parseTDebugLog(node, ctx) ||
+    parseTForEach(node, ctx) ||
+    parseTIf(node, ctx) ||
+    parseTCall(node, ctx) ||
+    parseTCallBlock(node, ctx) ||
+    parseTEscNode(node, ctx) ||
+    parseTKey(node, ctx) ||
+    parseTSlot(node, ctx) ||
+    parseTRawNode(node, ctx) ||
+    parseComponent(node, ctx) ||
+    parseDOMNode(node, ctx) ||
+    parseTSetNode(node, ctx) ||
+    parseTNode(node, ctx)
+  );
+}
+
+// -----------------------------------------------------------------------------
+// <t /> tag
+// -----------------------------------------------------------------------------
+
+function parseTNode(node: Element, ctx: ParsingContext): AST | null {
+  if (node.tagName !== "t") {
+    return null;
+  }
+  const children: AST[] = [];
+  for (let child of node.childNodes) {
+    const ast = parseNode(child, ctx);
+    if (ast) {
+      children.push(ast);
+    }
+  }
+  switch (children.length) {
+    case 0:
+      return null;
+    case 1:
+      return children[0];
+    default:
+      return {
+        type: ASTType.Multi,
+        content: children,
+      };
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Text and Comment Nodes
+// -----------------------------------------------------------------------------
+const lineBreakRE = /[\r\n]/;
+const whitespaceRE = /\s+/g;
+
+function parseTextCommentNode(node: ChildNode, ctx: ParsingContext): AST | null {
+  if (node.nodeType === 3) {
+    let value = node.textContent || "";
+    if (!ctx.inPreTag) {
+      if (lineBreakRE.test(value) && !value.trim()) {
+        return null;
+      }
+      value = value.replace(whitespaceRE, " ");
+    }
+
+    return { type: ASTType.Text, value };
+  } else if (node.nodeType === 8) {
+    return { type: ASTType.Comment, value: node.textContent || "" };
+  }
+  return null;
+}
+
+// -----------------------------------------------------------------------------
+// debugging
+// -----------------------------------------------------------------------------
+
+function parseTDebugLog(node: Element, ctx: ParsingContext): AST | null {
+  if (node.hasAttribute("t-debug")) {
+    node.removeAttribute("t-debug");
+    return {
+      type: ASTType.TDebug,
+      content: parseNode(node, ctx),
+    };
+  }
+
+  if (node.hasAttribute("t-log")) {
+    const expr = node.getAttribute("t-log")!;
+    node.removeAttribute("t-log");
+    return {
+      type: ASTType.TLog,
+      expr,
+      content: parseNode(node, ctx),
+    };
+  }
+  return null;
+}
+
+// -----------------------------------------------------------------------------
+// Regular dom node
+// -----------------------------------------------------------------------------
+
+function parseDOMNode(node: Element, ctx: ParsingContext): AST | null {
+  if (node.tagName === "t") {
+    return null;
+  }
+  const children: AST[] = [];
+  if (node.tagName === "pre") {
+    ctx = { inPreTag: true };
+  }
+  let ref = null;
+  if (node.hasAttribute("t-ref")) {
+    ref = node.getAttribute("t-ref");
+    node.removeAttribute("t-ref");
+  }
+
+  for (let child of node.childNodes) {
+    const ast = parseNode(child, ctx);
+    if (ast) {
+      children.push(ast);
+    }
+  }
+
+  const attrs: ASTDomNode["attrs"] = {};
+  const on: ASTDomNode["on"] = {};
+
+  for (let attr of node.getAttributeNames()) {
+    const value = node.getAttribute(attr)!;
+    if (attr.startsWith("t-on")) {
+      if (attr === "t-on") {
+        throw new Error("Missing event name with t-on directive");
+      }
+      on[attr.slice(5)] = value;
+    } else {
+      if (attr.startsWith("t-") && !attr.startsWith("t-att")) {
+        throw new Error(`Unknown QWeb directive: '${attr}'`);
+      }
+      attrs[attr] = value;
+    }
+  }
+  if (children.length === 1 && children[0].type === ASTType.TForEach) {
+    children[0].isOnlyChild = true;
+  }
+  return {
+    type: ASTType.DomNode,
+    tag: node.tagName,
+    attrs,
+    on,
+    ref,
+    content: children,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// t-esc
+// -----------------------------------------------------------------------------
+
+function parseTEscNode(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-esc")) {
+    return null;
+  }
+  const escValue = node.getAttribute("t-esc")!;
+  node.removeAttribute("t-esc");
+  const tesc: AST = {
+    type: ASTType.TEsc,
+    expr: escValue,
+    defaultValue: node.textContent || "",
+  };
+  let ref = node.getAttribute("t-ref");
+  node.removeAttribute("t-ref");
+  const ast = parseNode(node, ctx);
+  if (!ast) {
+    return tesc;
+  }
+  if (ast && ast.type === ASTType.DomNode) {
+    return {
+      type: ASTType.DomNode,
+      tag: ast.tag,
+      attrs: ast.attrs,
+      on: ast.on,
+      ref,
+      content: [tesc],
+    };
+  }
+  if (ast && ast.type === ASTType.TComponent) {
+    return {
+      ...ast,
+      slots: { default: tesc },
+    };
+  }
+  return tesc;
+}
+
+// -----------------------------------------------------------------------------
+// t-raw
+// -----------------------------------------------------------------------------
+
+function parseTRawNode(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-raw")) {
+    return null;
+  }
+  const expr = node.getAttribute("t-raw")!;
+  node.removeAttribute("t-raw");
+
+  const tRaw: AST = { type: ASTType.TRaw, expr, body: null };
+  const ref = node.getAttribute("t-ref");
+  node.removeAttribute("t-ref");
+  const ast = parseNode(node, ctx);
+  if (!ast) {
+    return tRaw;
+  }
+  if (ast && ast.type === ASTType.DomNode) {
+    tRaw.body = ast.content.length ? ast.content : null;
+    return {
+      type: ASTType.DomNode,
+      tag: ast.tag,
+      attrs: ast.attrs,
+      on: ast.on,
+      ref,
+      content: [tRaw],
+    };
+  }
+
+  return tRaw;
+}
+
+// -----------------------------------------------------------------------------
+// t-foreach and t-key
+// -----------------------------------------------------------------------------
+
+function parseTForEach(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-foreach")) {
+    return null;
+  }
+  const html = node.outerHTML;
+  const collection = node.getAttribute("t-foreach")!;
+  node.removeAttribute("t-foreach");
+  const elem = node.getAttribute("t-as") || "";
+  node.removeAttribute("t-as");
+  const key = node.getAttribute("t-key");
+  node.removeAttribute("t-key");
+  const memo = node.getAttribute("t-memo") || "";
+  node.removeAttribute("t-memo");
+  const body = parseNode(node, ctx);
+
+  if (!body) {
+    return null;
+  }
+
+  const hasNoTCall = !html.includes("t-call");
+  const hasNoFirst = hasNoTCall && !html.includes(`${elem}_first`);
+  const hasNoLast = hasNoTCall && !html.includes(`${elem}_last`);
+  const hasNoIndex = hasNoTCall && !html.includes(`${elem}_index`);
+  const hasNoValue = hasNoTCall && !html.includes(`${elem}_value`);
+
+  return {
+    type: ASTType.TForEach,
+    collection,
+    elem,
+    body,
+    memo,
+    key,
+    isOnlyChild: false,
+    hasNoComponent: hasNoComponent(body),
+    hasNoFirst,
+    hasNoLast,
+    hasNoIndex,
+    hasNoValue,
+  };
+}
+
+/**
+ * @returns true if we are sure the ast does not contain any component
+ */
+function hasNoComponent(ast: AST): boolean {
+  switch (ast.type) {
+    case ASTType.TComponent:
+    case ASTType.TRaw:
+    case ASTType.TCall:
+    case ASTType.TCallBlock:
+    case ASTType.TSlot:
+      return false;
+    case ASTType.TSet:
+    case ASTType.Text:
+    case ASTType.Comment:
+    case ASTType.TEsc:
+      return true;
+    case ASTType.TKey:
+      return hasNoComponent(ast.content);
+    case ASTType.TDebug:
+    case ASTType.TLog:
+      return ast.content ? hasNoComponent(ast.content) : true;
+    case ASTType.TForEach:
+      return ast.hasNoComponent;
+    case ASTType.Multi:
+    case ASTType.DomNode: {
+      for (let elem of ast.content) {
+        if (!hasNoComponent(elem)) {
+          return false;
+        }
+      }
+      return true;
+    }
+    case ASTType.TIf: {
+      if (!hasNoComponent(ast.content)) {
+        return false;
+      }
+      if (ast.tElif) {
+        for (let elem of ast.tElif) {
+          if (!hasNoComponent(elem.content)) {
+            return false;
+          }
+        }
+      }
+      if (ast.tElse && !hasNoComponent(ast.tElse)) {
+        return false;
+      }
+      return true;
+    }
+  }
+}
+
+function parseTKey(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-key")) {
+    return null;
+  }
+  const key = node.getAttribute("t-key")!;
+  node.removeAttribute("t-key");
+  const body = parseNode(node, ctx);
+  if (!body) {
+    return null;
+  }
+  return { type: ASTType.TKey, expr: key, content: body };
+}
+
+// -----------------------------------------------------------------------------
+// t-call
+// -----------------------------------------------------------------------------
+
+function parseTCall(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-call")) {
+    return null;
+  }
+  const subTemplate = node.getAttribute("t-call")!;
+
+  node.removeAttribute("t-call");
+  if (node.tagName !== "t") {
+    const ast = parseNode(node, ctx);
+    const tcall: AST = { type: ASTType.TCall, name: subTemplate, body: null };
+    if (ast && ast.type === ASTType.DomNode) {
+      ast.content = [tcall];
+      return ast;
+    }
+    if (ast && ast.type === ASTType.TComponent) {
+      return {
+        ...ast,
+        slots: { default: tcall },
+      };
+    }
+  }
+  const body: AST[] = [];
+  for (let child of node.childNodes) {
+    const ast = parseNode(child, ctx);
+    if (ast) {
+      body.push(ast);
+    }
+  }
+
+  return {
+    type: ASTType.TCall,
+    name: subTemplate,
+    body: body.length ? body : null,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// t-call-block
+// -----------------------------------------------------------------------------
+
+function parseTCallBlock(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-call-block")) {
+    return null;
+  }
+  const name = node.getAttribute("t-call-block")!;
+  return {
+    type: ASTType.TCallBlock,
+    name,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// t-if
+// -----------------------------------------------------------------------------
+
+function parseTIf(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-if")) {
+    return null;
+  }
+  const condition = node.getAttribute("t-if")!;
+  node.removeAttribute("t-if");
+  const content = parseNode(node, ctx);
+  if (!content) {
+    throw new Error("hmmm");
+  }
+
+  let nextElement = node.nextElementSibling;
+  // t-elifs
+  const tElifs: any[] = [];
+  while (nextElement && nextElement.hasAttribute("t-elif")) {
+    const condition = nextElement.getAttribute("t-elif");
+    nextElement.removeAttribute("t-elif");
+    const tElif = parseNode(nextElement, ctx);
+    const next = nextElement.nextElementSibling;
+    nextElement.remove();
+    nextElement = next;
+    if (tElif) {
+      tElifs.push({ condition, content: tElif });
+    }
+  }
+
+  // t-else
+  let tElse: AST | null = null;
+  if (nextElement && nextElement.hasAttribute("t-else")) {
+    nextElement.removeAttribute("t-else");
+    tElse = parseNode(nextElement, ctx);
+    nextElement.remove();
+  }
+
+  return {
+    type: ASTType.TIf,
+    condition,
+    content,
+    tElif: tElifs.length ? tElifs : null,
+    tElse,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// t-set directive
+// -----------------------------------------------------------------------------
+
+function parseTSetNode(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-set")) {
+    return null;
+  }
+  const name = node.getAttribute("t-set")!;
+  const value = node.getAttribute("t-value") || null;
+  const defaultValue = node.innerHTML === node.textContent ? node.textContent || null : null;
+  let body: AST[] | null = null;
+  if (node.textContent !== node.innerHTML) {
+    body = [];
+    for (let child of node.childNodes) {
+      let childAst = parseNode(child, ctx);
+      if (childAst) {
+        body.push(childAst);
+      }
+    }
+  }
+  return { type: ASTType.TSet, name, value, defaultValue, body };
+}
+
+// -----------------------------------------------------------------------------
+// Components
+// -----------------------------------------------------------------------------
+
+function parseComponent(node: Element, ctx: ParsingContext): AST | null {
+  let name = node.tagName;
+  const firstLetter = name[0];
+  let isDynamic = node.hasAttribute("t-component");
+
+  if (!(firstLetter === firstLetter.toUpperCase() || isDynamic)) {
+    return null;
+  }
+  if (isDynamic) {
+    name = node.getAttribute("t-component")!;
+    node.removeAttribute("t-component");
+  }
+
+  const props: ASTComponent["props"] = {};
+  const handlers: ASTComponent["handlers"] = {};
+  for (let name of node.getAttributeNames()) {
+    const value = node.getAttribute(name)!;
+    if (name.startsWith("t-on-")) {
+      handlers[name.slice(5)] = value;
+    } else {
+      props[name] = value;
+    }
+  }
+
+  const slots: ASTComponent["slots"] = {};
+  if (node.hasChildNodes()) {
+    const clone = <Element>node.cloneNode(true);
+
+    // named slots
+    const slotNodes = Array.from(clone.querySelectorAll("[t-set-slot]"));
+    for (let slotNode of slotNodes) {
+      const name = slotNode.getAttribute("t-set-slot")!;
+
+      // check if this is defined in a sub component (in which case it should
+      // be ignored)
+      let el = slotNode.parentElement!;
+      let isInSubComponent = false;
+      while (el !== clone) {
+        if (el!.hasAttribute("t-component") || el!.tagName[0] === el!.tagName[0].toUpperCase()) {
+          isInSubComponent = true;
+          break;
+        }
+        el = el.parentElement!;
+      }
+      if (isInSubComponent) {
+        continue;
+      }
+
+      slotNode.removeAttribute("t-set-slot");
+      slotNode.remove();
+      const slotAst = parseNode(slotNode, ctx);
+      if (slotAst) {
+        slots[name] = slotAst;
+      }
+    }
+
+    // default slot
+    const defaultContent = parseChildNodes(clone, ctx);
+    if (defaultContent) {
+      slots.default = defaultContent;
+    }
+  }
+  return { type: ASTType.TComponent, name, isDynamic, props, handlers, slots };
+}
+
+// -----------------------------------------------------------------------------
+// Slots
+// -----------------------------------------------------------------------------
+
+function parseTSlot(node: Element, ctx: ParsingContext): AST | null {
+  if (!node.hasAttribute("t-slot")) {
+    return null;
+  }
+  return {
+    type: ASTType.TSlot,
+    name: node.getAttribute("t-slot")!,
+    defaultContent: parseChildNodes(node, ctx),
+  };
+}
+
+// -----------------------------------------------------------------------------
+// helpers
+// -----------------------------------------------------------------------------
+
+function parseChildNodes(node: Element, ctx: ParsingContext): AST | null {
+  const children: AST[] = [];
+  for (let child of node.childNodes) {
+    const childAst = parseNode(child, ctx);
+    if (childAst) {
+      children.push(childAst);
+    }
+  }
+  switch (children.length) {
+    case 0:
+      return null;
+    case 1:
+      return children[0];
+    default:
+      return { type: ASTType.Multi, content: children };
+  }
+}
+function parseXML(xml: string): Document {
+  const parser = new DOMParser();
+
+  const doc = parser.parseFromString(xml, "text/xml");
+  if (doc.getElementsByTagName("parsererror").length) {
+    let msg = "Invalid XML in template.";
+    const parsererrorText = doc.getElementsByTagName("parsererror")[0].textContent;
+    if (parsererrorText) {
+      msg += "\nThe parser has produced the following error message:\n" + parsererrorText;
+      const re = /\d+/g;
+      const firstMatch = re.exec(parsererrorText);
+      if (firstMatch) {
+        const lineNumber = Number(firstMatch[0]);
+        const line = xml.split("\n")[lineNumber - 1];
+        const secondMatch = re.exec(parsererrorText);
+        if (line && secondMatch) {
+          const columnIndex = Number(secondMatch[0]) - 1;
+          if (line[columnIndex]) {
+            msg +=
+              `\nThe error might be located at xml line ${lineNumber} column ${columnIndex}\n` +
+              `${line}\n${"-".repeat(columnIndex - 1)}^`;
+          }
+        }
+      }
+    }
+    throw new Error(msg);
+  }
+  let tbranch = doc.querySelectorAll("[t-elif], [t-else]");
+  for (let i = 0, ilen = tbranch.length; i < ilen; i++) {
+    let node = tbranch[i];
+    let prevElem = node.previousElementSibling!;
+    let pattr = (name: string) => prevElem.getAttribute(name);
+    let nattr = (name: string) => +!!node.getAttribute(name);
+    if (prevElem && (pattr("t-if") || pattr("t-elif"))) {
+      if (pattr("t-foreach")) {
+        throw new Error(
+          "t-if cannot stay at the same level as t-foreach when using t-elif or t-else"
+        );
+      }
+      if (
+        ["t-if", "t-elif", "t-else"].map(nattr).reduce(function (a, b) {
+          return a + b;
+        }) > 1
+      ) {
+        throw new Error("Only one conditional branching directive is allowed per node");
+      }
+      // All text (with only spaces) and comment nodes (nodeType 8) between
+      // branch nodes are removed
+      let textNode;
+      while ((textNode = node.previousSibling) !== prevElem) {
+        if (textNode!.nodeValue!.trim().length && textNode!.nodeType !== 8) {
+          throw new Error("text is not allowed between branching directives");
+        }
+        textNode!.remove();
+      }
+    } else {
+      throw new Error(
+        "t-elif and t-else directives must be preceded by a t-if or t-elif directive"
+      );
+    }
+  }
+
+  return doc;
+}

src/qweb/template_helpers.ts

@@ -0,0 +1,129 @@
+// import { compileTemplate, Template } from "./qweb/index";
+import { BDom, createBlock, html, list, multi, text, toggler } from "../blockdom";
+import { component } from "../component/component_node";
+import { Template, compileTemplate } from "./compiler";
+
+const bdom = { text, createBlock, list, multi, html, toggler, component };
+
+export const globalTemplates: { [key: string]: string } = {};
+
+function withDefault(value: any, defaultValue: any): any {
+  return value === undefined || value === null || value === false ? defaultValue : value;
+}
+
+function callSlot(
+  ctx: any,
+  parent: any,
+  key: string,
+  name: string,
+  defaultSlot?: (ctx: any, key: string) => BDom,
+  dynamic?: boolean
+): BDom | null {
+  const slots = ctx.__owl__.slots;
+  const slotFn = slots[name];
+  const slotBDom = slotFn ? slotFn(parent, key) : null;
+  if (defaultSlot) {
+    let child1: BDom | undefined = undefined;
+    let child2: BDom | undefined = undefined;
+    // const result = new BMulti(2);
+    if (slotBDom) {
+      child1 = dynamic ? toggler(name, slotBDom) : slotBDom;
+    } else {
+      child2 = defaultSlot(parent, key);
+    }
+    return multi([child1, child2]);
+  }
+  return slotBDom;
+}
+
+function capture(ctx: any): any {
+  const component = ctx.__owl__.component;
+  const result = Object.create(component);
+  for (let k in ctx) {
+    result[k] = ctx[k];
+  }
+  return result;
+}
+
+function withKey(elem: any, k: string) {
+  elem.key = k;
+  return elem;
+}
+
+function prepareList(collection: any): [any[], any[], number, any[]] {
+  let keys: any[];
+  let values: any[];
+
+  if (Array.isArray(collection)) {
+    keys = collection;
+    values = collection;
+  } else if (collection) {
+    values = Object.keys(collection);
+    keys = Object.values(collection);
+  } else {
+    throw new Error("Invalid loop expression");
+  }
+  const n = values.length;
+  return [keys, values, n, new Array(n)];
+}
+export const UTILS = {
+  // elem,
+  // setText,
+  withDefault,
+  zero: Symbol("zero"),
+  callSlot,
+  capture,
+  // toClassObj,
+  withKey,
+  prepareList,
+  shallowEqual,
+};
+
+export class TemplateSet {
+  rawTemplates: { [name: string]: string } = Object.create(globalTemplates);
+  templates: { [name: string]: Template } = {};
+  utils: typeof UTILS;
+
+  constructor() {
+    const call = (subTemplate: string, ctx: any, parent: any) => {
+      const template = this.getTemplate(subTemplate);
+      return toggler(subTemplate, template(ctx, parent));
+    };
+
+    const getTemplate = (name: string) => this.getTemplate(name);
+    this.utils = Object.assign({}, UTILS, { getTemplate, call });
+  }
+
+  addTemplate(name: string, template: string, options: { allowDuplicate?: boolean } = {}) {
+    if (name in this.rawTemplates && !options.allowDuplicate) {
+      throw new Error(`Template ${name} already defined`);
+    }
+    this.rawTemplates[name] = template;
+  }
+
+  getTemplate(name: string): Template {
+    if (!(name in this.templates)) {
+      const rawTemplate = this.rawTemplates[name];
+      if (rawTemplate === undefined) {
+        throw new Error(`Missing template: "${name}"`);
+      }
+      const templateFn = compileTemplate(rawTemplate, name);
+
+      // first add a function to lazily get the template, in case there is a
+      // recursive call to the template name
+      this.templates[name] = (context, parent) => this.templates[name](context, parent);
+      const template = templateFn(bdom, this.utils);
+      this.templates[name] = template;
+    }
+    return this.templates[name];
+  }
+}
+
+function shallowEqual(l1: any[], l2: any[]): boolean {
+  for (let i = 0, l = l1.length; i < l; i++) {
+    if (l1[i] !== l2[i]) {
+      return false;
+    }
+  }
+  return true;
+}

src/qweb_core.ts

@@ -1,733 +0,0 @@
-import { VNode, h } from "./vdom";
-
-/**
- * Owl QWeb Engine
- *
- * In this file, you will find a QWeb engine/template compiler.  It is the core
- * of how Owl component works.
- *
- * Briefly, Owl QWeb compiles XML templates into functions that output a virtual
- * DOM representation.
- *
- * We have here:
- * - a CompilationContext class, which is an internal object that contains all
- *   compilation specific information, while a template is being compiled.
- * - a QWeb class: this is the code of the QWeb compiler.
- *
- * Note that this file does not contain the implementation of the QWeb
- * directives (see qweb_directives.ts and qweb_extensions.ts).
- */
-
-//------------------------------------------------------------------------------
-// Types
-//------------------------------------------------------------------------------
-export type EvalContext = { [key: string]: any };
-export type CompiledTemplate = (context: EvalContext, extra: any) => VNode;
-
-interface Template {
-  elem: Element;
-  fn: CompiledTemplate;
-}
-
-interface CompilationInfo {
-  node: Element;
-  qweb: QWeb;
-  ctx: Context;
-  fullName: string;
-  value: string;
-}
-
-interface NodeCreationCompilationInfo extends CompilationInfo {
-  nodeID: number;
-  addNodeHook: Function;
-}
-
-export interface Directive {
-  name: string;
-  extraNames?: string[];
-  priority: number;
-  // if return true, then directive is fully applied and there is no need to
-  // keep processing node. Otherwise, we keep going.
-  atNodeEncounter?(info: CompilationInfo): boolean | void;
-  atNodeCreation?(info: NodeCreationCompilationInfo): void;
-  finalize?(info: CompilationInfo): void;
-}
-
-//------------------------------------------------------------------------------
-// Const/global stuff/helpers
-//------------------------------------------------------------------------------
-const RESERVED_WORDS = "true,false,NaN,null,undefined,debugger,console,window,in,instanceof,new,function,return,this,typeof,eval,void,Math,RegExp,Array,Object,Date".split(
-  ","
-);
-
-const WORD_REPLACEMENT = {
-  and: "&&",
-  or: "||",
-  gt: ">",
-  gte: ">=",
-  lt: "<",
-  lte: "<="
-};
-
-const DISABLED_TAGS = [
-  "input",
-  "textarea",
-  "button",
-  "select",
-  "option",
-  "optgroup"
-];
-
-const lineBreakRE = /[\r\n]/;
-const whitespaceRE = /\s+/g;
-
-const DIRECTIVE_NAMES = {
-  name: 1,
-  att: 1,
-  attf: 1,
-  key: 1
-};
-
-const DIRECTIVES: Directive[] = [];
-
-const NODE_HOOKS_PARAMS = {
-  create: "(_, n)",
-  insert: "vn",
-  remove: "(vn, rm)"
-};
-
-export const UTILS = {
-  h: h,
-  objectToAttrString(obj: Object): string {
-    let classes: string[] = [];
-    for (let k in obj) {
-      if (obj[k]) {
-        classes.push(k);
-      }
-    }
-    return classes.join(" ");
-  }
-};
-
-function parseXML(xml: string): Document {
-  const parser = new DOMParser();
-  const doc = parser.parseFromString(xml, "text/xml");
-  if (doc.getElementsByTagName("parsererror").length) {
-    throw new Error("Invalid XML in template");
-  }
-  return doc;
-}
-
-let nextID = 1;
-
-//------------------------------------------------------------------------------
-// QWeb rendering engine
-//------------------------------------------------------------------------------
-export class QWeb {
-  templates: { [name: string]: Template } = {};
-  utils = UTILS;
-
-  // the id field is useful to be able to hash qweb instances.  The current
-  // use case is that component's templates are qweb dependant, and need to be
-  // able to map a qweb instance to a template name.
-  id = nextID++;
-
-  constructor(data?: string) {
-    if (data) {
-      this.addTemplates(data);
-    }
-    this.addTemplate("default", "<div></div>");
-  }
-
-  static addDirective(directive: Directive) {
-    DIRECTIVES.push(directive);
-    DIRECTIVE_NAMES[directive.name] = 1;
-    DIRECTIVES.sort((d1, d2) => d1.priority - d2.priority);
-    if (directive.extraNames) {
-      directive.extraNames.forEach(n => (DIRECTIVE_NAMES[n] = 1));
-    }
-  }
-
-  /**
-   * Add a template to the internal template map.  Note that it is not
-   * immediately compiled.
-   */
-  addTemplate(name: string, xmlString: string) {
-    const doc = parseXML(xmlString);
-    if (!doc.firstChild) {
-      throw new Error("Invalid template (should not be empty)");
-    }
-    this._addTemplate(name, <Element>doc.firstChild);
-  }
-
-  /**
-   * Load templates from a xml (as a string).  This will look up for the first
-   * <templates> tag, and will consider each child of this as a template, with
-   * the name given by the t-name attribute.
-   */
-  addTemplates(xmlstr: string) {
-    const doc = parseXML(xmlstr);
-    const templates = doc.getElementsByTagName("templates")[0];
-    if (!templates) {
-      return;
-    }
-    for (let elem of <any>templates.children) {
-      const name = elem.getAttribute("t-name");
-      this._addTemplate(name, elem);
-    }
-  }
-
-  _addTemplate(name: string, elem: Element) {
-    if (name in this.templates) {
-      throw new Error(`Template ${name} already defined`);
-    }
-    this._processTemplate(elem);
-    const template = {
-      elem,
-      fn: (context, extra) => {
-        const compiledFunction = this._compile(name, elem);
-        template.fn = compiledFunction;
-        return compiledFunction.call(this, context, extra);
-      }
-    };
-    this.templates[name] = template;
-  }
-
-  _processTemplate(elem: Element) {
-    let tbranch = elem.querySelectorAll("[t-elif], [t-else]");
-    for (let i = 0, ilen = tbranch.length; i < ilen; i++) {
-      let node = tbranch[i];
-      let prevElem = node.previousElementSibling!;
-      let pattr = function(name) {
-        return prevElem.getAttribute(name);
-      };
-      let nattr = function(name) {
-        return +!!node.getAttribute(name);
-      };
-      if (prevElem && (pattr("t-if") || pattr("t-elif"))) {
-        if (pattr("t-foreach")) {
-          throw new Error(
-            "t-if cannot stay at the same level as t-foreach when using t-elif or t-else"
-          );
-        }
-        if (
-          ["t-if", "t-elif", "t-else"].map(nattr).reduce(function(a, b) {
-            return a + b;
-          }) > 1
-        ) {
-          throw new Error(
-            "Only one conditional branching directive is allowed per node"
-          );
-        }
-        // All text nodes between branch nodes are removed
-        let textNode;
-        while ((textNode = node.previousSibling) !== prevElem) {
-          if (textNode.nodeValue.trim().length) {
-            throw new Error("text is not allowed between branching directives");
-          }
-          textNode.remove();
-        }
-      } else {
-        throw new Error(
-          "t-elif and t-else directives must be preceded by a t-if or t-elif directive"
-        );
-      }
-    }
-  }
-  /**
-   * Render a template
-   *
-   * @param {string} name the template should already have been added
-   */
-  render(name: string, context: EvalContext = {}, extra: any = null): VNode {
-    const template = this.templates[name];
-    if (!template) {
-      throw new Error(`Template ${name} does not exist`);
-    }
-    return template.fn.call(this, context, extra);
-  }
-
-  _compile(name: string, elem: Element): CompiledTemplate {
-    const isDebug = elem.attributes.hasOwnProperty("t-debug");
-    const ctx = new Context(name);
-    this._compileNode(elem, ctx);
-
-    if (ctx.shouldProtectContext) {
-      ctx.code.unshift("    context = Object.create(context);");
-    }
-    if (ctx.shouldDefineOwner) {
-      // this is necessary to prevent some directives (t-forach for ex) to
-      // pollute the rendering context by adding some keys in it.
-      ctx.code.unshift("    let owner = context;");
-    }
-
-    if (!ctx.rootNode) {
-      throw new Error("A template should have one root node");
-    }
-    ctx.addLine(`return vn${ctx.rootNode};`);
-    let template;
-    try {
-      template = new Function(
-        "context",
-        "extra",
-        ctx.code.join("\n")
-      ) as CompiledTemplate;
-    } catch (e) {
-      throw new Error(
-        `Invalid generated code while compiling template '${ctx.templateName.replace(
-          /`/g,
-          "'"
-        )}': ${e.message}`
-      );
-    }
-    if (isDebug) {
-      console.log(
-        `Template: ${this.templates[name].elem.outerHTML}\nCompiled code:\n` +
-          template.toString()
-      );
-    }
-    return template;
-  }
-
-  /**
-   * Generate code from an xml node
-   *
-   */
-  _compileNode(node: ChildNode, ctx: Context) {
-    if (!(node instanceof Element)) {
-      // this is a text node, there are no directive to apply
-      let text = node.textContent!;
-      if (!ctx.inPreTag) {
-        if (lineBreakRE.test(text) && !text.trim()) {
-          return;
-        }
-        text = text.replace(whitespaceRE, " ");
-      }
-      if (ctx.parentNode) {
-        ctx.addLine(`c${ctx.parentNode}.push({text: \`${text}\`});`);
-      } else {
-        // this is an unusual situation: this text node is the result of the
-        // template rendering.
-        let nodeID = ctx.generateID();
-        ctx.addLine(`var vn${nodeID} = {text: \`${text}\`};`);
-        ctx.rootContext.rootNode = nodeID;
-        ctx.rootContext.parentNode = nodeID;
-      }
-      return;
-    }
-
-    const attributes = (<Element>node).attributes;
-
-    const validDirectives: {
-      directive: Directive;
-      value: string;
-      fullName: string;
-    }[] = [];
-
-    let withHandlers = false;
-
-    // maybe this is not optimal: we iterate on all attributes here, and again
-    // just after for each directive.
-    for (let i = 0; i < attributes.length; i++) {
-      let attrName = attributes[i].name;
-      if (attrName.startsWith("t-")) {
-        let dName = attrName.slice(2).split("-")[0];
-        if (!(dName in DIRECTIVE_NAMES)) {
-          throw new Error(`Unknown QWeb directive: '${attrName}'`);
-        }
-      }
-    }
-
-    for (let directive of DIRECTIVES) {
-      let fullName;
-      let value;
-      for (let i = 0; i < attributes.length; i++) {
-        const name = attributes[i].name;
-        if (
-          name === "t-" + directive.name ||
-          name.startsWith("t-" + directive.name + "-")
-        ) {
-          fullName = name;
-          value = attributes[i].textContent;
-          validDirectives.push({ directive, value, fullName });
-          if (directive.name === "on") {
-            withHandlers = true;
-          }
-        }
-      }
-    }
-    for (let { directive, value, fullName } of validDirectives) {
-      if (directive.atNodeEncounter) {
-        const isDone = directive.atNodeEncounter({
-          node,
-          qweb: this,
-          ctx,
-          fullName,
-          value
-        });
-        if (isDone) {
-          return;
-        }
-      }
-    }
-
-    if (node.nodeName !== "t") {
-      let nodeID = this._compileGenericNode(node, ctx, withHandlers);
-      ctx = ctx.withParent(nodeID);
-      let nodeHooks = {};
-      let addNodeHook = function(hook, handler) {
-        nodeHooks[hook] = nodeHooks[hook] || [];
-        nodeHooks[hook].push(handler);
-      };
-
-      for (let { directive, value, fullName } of validDirectives) {
-        if (directive.atNodeCreation) {
-          directive.atNodeCreation({
-            node,
-            qweb: this,
-            ctx,
-            fullName,
-            value,
-            nodeID,
-            addNodeHook
-          });
-        }
-      }
-
-      if (Object.keys(nodeHooks).length) {
-        ctx.addLine(`p${nodeID}.hook = {`);
-        for (let hook in nodeHooks) {
-          ctx.addLine(`  ${hook}: ${NODE_HOOKS_PARAMS[hook]} => {`);
-          for (let handler of nodeHooks[hook]) {
-            ctx.addLine(`    ${handler}`);
-          }
-          ctx.addLine(`  },`);
-        }
-        ctx.addLine(`};`);
-      }
-    }
-    if (node.nodeName === "pre") {
-      ctx = ctx.subContext("inPreTag", true);
-    }
-
-    this._compileChildren(node, ctx);
-
-    for (let { directive, value, fullName } of validDirectives) {
-      if (directive.finalize) {
-        directive.finalize({ node, qweb: this, ctx, fullName, value });
-      }
-    }
-  }
-
-  _compileGenericNode(
-    node: ChildNode,
-    ctx: Context,
-    withHandlers: boolean = true
-  ): number {
-    // nodeType 1 is generic tag
-    if (node.nodeType !== 1) {
-      throw new Error("unsupported node type");
-    }
-    const attributes = (<Element>node).attributes;
-    const attrs: string[] = [];
-    const props: string[] = [];
-    const tattrs: number[] = [];
-
-    function handleBooleanProps(key, val) {
-      let isProp = false;
-      if (node.nodeName === "input" && key === "checked") {
-        let type = (<Element>node).getAttribute("type");
-        if (type === "checkbox" || type === "radio") {
-          isProp = true;
-        }
-      }
-      if (node.nodeName === "option" && key === "selected") {
-        isProp = true;
-      }
-      if (key === "disabled" && DISABLED_TAGS.indexOf(node.nodeName) > -1) {
-        isProp = true;
-      }
-      if (
-        (key === "readonly" && node.nodeName === "input") ||
-        node.nodeName === "textarea"
-      ) {
-        isProp = true;
-      }
-      if (isProp) {
-        props.push(`${key}: _${val}`);
-      }
-    }
-    function formatter(expr) {
-      return "${" + ctx.formatExpression(expr) + "}";
-    }
-
-    for (let i = 0; i < attributes.length; i++) {
-      let name = attributes[i].name;
-      const value = attributes[i].textContent!;
-
-      // regular attributes
-      if (
-        !name.startsWith("t-") &&
-        !(<Element>node).getAttribute("t-attf-" + name)
-      ) {
-        const attID = ctx.generateID();
-        ctx.addLine(`var _${attID} = '${value}';`);
-        if (!name.match(/^[a-zA-Z]+$/)) {
-          // attribute contains 'non letters' => we want to quote it
-          name = '"' + name + '"';
-        }
-        attrs.push(`${name}: _${attID}`);
-        handleBooleanProps(name, attID);
-      }
-
-      // dynamic attributes
-      if (name.startsWith("t-att-")) {
-        let attName = name.slice(6);
-        let formattedValue = ctx.formatExpression(ctx.getValue(value!));
-        if (
-          formattedValue[0] === "{" &&
-          formattedValue[formattedValue.length - 1] === "}"
-        ) {
-          formattedValue = `this.utils.objectToAttrString(${formattedValue})`;
-        }
-        const attID = ctx.generateID();
-        if (!attName.match(/^[a-zA-Z]+$/)) {
-          // attribute contains 'non letters' => we want to quote it
-          attName = '"' + attName + '"';
-        }
-        // we need to combine dynamic with non dynamic attributes:
-        // class="a" t-att-class="'yop'" should be rendered as class="a yop"
-        const attValue = (<Element>node).getAttribute(attName);
-        if (attValue) {
-          const attValueID = ctx.generateID();
-          ctx.addLine(`var _${attValueID} = ${formattedValue};`);
-          formattedValue = `'${attValue}' + (_${attValueID} ? ' ' + _${attValueID} : '')`;
-          const attrIndex = attrs.findIndex(att =>
-            att.startsWith(attName + ":")
-          );
-          attrs.splice(attrIndex, 1);
-        }
-        ctx.addLine(`var _${attID} = ${formattedValue};`);
-        attrs.push(`${attName}: _${attID}`);
-        handleBooleanProps(attName, attID);
-      }
-
-      if (name.startsWith("t-attf-")) {
-        let attName = name.slice(7);
-        if (!attName.match(/^[a-zA-Z]+$/)) {
-          // attribute contains 'non letters' => we want to quote it
-          attName = '"' + attName + '"';
-        }
-        const formattedExpr = value!
-          .replace(/\{\{.*?\}\}/g, s => formatter(s.slice(2, -2)))
-          .replace(/\#\{.*?\}/g, s => formatter(s.slice(2, -1)));
-        const attID = ctx.generateID();
-        let staticVal = (<Element>node).getAttribute(attName);
-        if (staticVal) {
-          ctx.addLine(
-            `var _${attID} = '${staticVal} ' + \`${formattedExpr}\`;`
-          );
-        } else {
-          ctx.addLine(`var _${attID} = \`${formattedExpr}\`;`);
-        }
-        attrs.push(`${attName}: _${attID}`);
-      }
-
-      // t-att= attributes
-      if (name === "t-att") {
-        let id = ctx.generateID();
-        ctx.addLine(`var _${id} = ${ctx.formatExpression(value!)};`);
-        tattrs.push(id);
-      }
-    }
-    let nodeID = ctx.generateID();
-    let nodeKey: any = (<Element>node).getAttribute("t-key");
-    if (nodeKey) {
-      nodeKey = ctx.formatExpression(nodeKey);
-    } else {
-      nodeKey = nodeID;
-    }
-    const parts = [`key:${nodeKey}`];
-    if (attrs.length + tattrs.length > 0) {
-      parts.push(`attrs:{${attrs.join(",")}}`);
-    }
-    if (props.length > 0) {
-      parts.push(`props:{${props.join(",")}}`);
-    }
-    if (withHandlers) {
-      parts.push(`on:{}`);
-    }
-
-    ctx.addLine(`let c${nodeID} = [], p${nodeID} = {${parts.join(",")}};`);
-    for (let id of tattrs) {
-      ctx.addIf(`_${id} instanceof Array`);
-      ctx.addLine(`p${nodeID}.attrs[_${id}[0]] = _${id}[1];`);
-      ctx.addElse();
-      ctx.addLine(`for (let key in _${id}) {`);
-      ctx.indent();
-      ctx.addLine(`p${nodeID}.attrs[key] = _${id}[key];`);
-      ctx.dedent();
-      ctx.addLine(`}`);
-      ctx.closeIf();
-    }
-    ctx.addLine(
-      `var vn${nodeID} = h('${node.nodeName}', p${nodeID}, c${nodeID});`
-    );
-    if (ctx.parentNode) {
-      ctx.addLine(`c${ctx.parentNode}.push(vn${nodeID});`);
-    }
-
-    return nodeID;
-  }
-
-  _compileChildren(node: ChildNode, ctx: Context) {
-    if (node.childNodes.length > 0) {
-      for (let child of Array.from(node.childNodes)) {
-        this._compileNode(child, ctx);
-      }
-    }
-  }
-}
-
-//------------------------------------------------------------------------------
-// Compilation Context
-//------------------------------------------------------------------------------
-export class Context {
-  nextID: number = 1;
-  code: string[] = [];
-  variables: { [key: string]: any } = {};
-  definedVariables: { [key: string]: string } = {};
-  escaping: boolean = false;
-  parentNode: number | null = null;
-  rootNode: number | null = null;
-  indentLevel: number = 0;
-  rootContext: Context;
-  caller: Element | undefined;
-  shouldDefineOwner: boolean = false;
-  shouldProtectContext: boolean = false;
-  inLoop: boolean = false;
-  inPreTag: boolean = false;
-  templateName: string;
-
-  constructor(name?: string) {
-    this.rootContext = this;
-    this.templateName = name || "noname";
-    this.addLine("var h = this.utils.h;");
-  }
-
-  generateID(): number {
-    const id = this.rootContext.nextID++;
-    return id;
-  }
-
-  withParent(node: number): Context {
-    if (this === this.rootContext && this.parentNode) {
-      throw new Error("A template should not have more than one root node");
-    }
-    if (!this.rootContext.rootNode) {
-      this.rootContext.rootNode = node;
-    }
-    return this.subContext("parentNode", node);
-  }
-
-  subContext(key: keyof Context, value: any): Context {
-    const newContext = Object.create(this);
-    newContext[key] = value;
-    return newContext;
-  }
-
-  indent() {
-    this.indentLevel++;
-  }
-
-  dedent() {
-    this.indentLevel--;
-  }
-
-  addLine(line: string) {
-    const prefix = new Array(this.indentLevel + 2).join("    ");
-    this.code.push(prefix + line);
-  }
-
-  addIf(condition: string) {
-    this.addLine(`if (${condition}) {`);
-    this.indent();
-  }
-
-  addElse() {
-    this.dedent();
-    this.addLine("} else {");
-    this.indent();
-  }
-
-  closeIf() {
-    this.dedent();
-    this.addLine("}");
-  }
-
-  getValue(val: any): any {
-    return val in this.variables ? this.getValue(this.variables[val]) : val;
-  }
-
-  formatExpression(e: string): string {
-    e = e.trim();
-    if (e[0] === "{" && e[e.length - 1] === "}") {
-      const innerExpr = e
-        .slice(1, -1)
-        .split(",")
-        .map(p => {
-          let [key, val] = p.trim().split(":");
-          if (key === "") {
-            return "";
-          }
-          if (!val) {
-            val = key;
-          }
-          return `${key}: ${this.formatExpression(val)}`;
-        })
-        .join(",");
-      return "{" + innerExpr + "}";
-    }
-
-    // Thanks CHM for this code...
-    const chars = e.split("");
-    let instring = "";
-    let invar = "";
-    let invarPos = 0;
-    let r = "";
-    chars.push(" ");
-    for (var i = 0, ilen = chars.length; i < ilen; i++) {
-      var c = chars[i];
-      if (instring.length) {
-        if (c === instring && chars[i - 1] !== "\\") {
-          instring = "";
-        }
-      } else if (c === '"' || c === "'") {
-        instring = c;
-      } else if (c.match(/[a-zA-Z_\$]/) && !invar.length) {
-        invar = c;
-        invarPos = i;
-        continue;
-      } else if (c.match(/\W/) && invar.length) {
-        // TODO: Should check for possible spaces before dot
-        if (chars[invarPos - 1] !== "." && RESERVED_WORDS.indexOf(invar) < 0) {
-          if (!(invar in this.definedVariables)) {
-            invar =
-              WORD_REPLACEMENT[invar] ||
-              (invar in this.variables &&
-                this.formatExpression(this.variables[invar])) ||
-              "context['" + invar + "']";
-          }
-        }
-        r += invar;
-        invar = "";
-      } else if (invar.length) {
-        invar += c;
-        continue;
-      }
-      r += c;
-    }
-    const result = r.slice(0, -1);
-    return result;
-  }
-}

src/qweb_directives.ts

@@ -1,317 +0,0 @@
-import { Context, QWeb, UTILS } from "./qweb_core";
-
-/**
- * Owl QWeb Directives
- *
- * This file contains the implementation of most standard QWeb directives:
- * - t-esc
- * - t-raw
- * - t-set/t-value
- * - t-if/t-elif/t-else
- * - t-call
- * - t-foreach/t-as
- * - t-debug
- * - t-log
- */
-
-
-//------------------------------------------------------------------------------
-// t-esc and t-raw
-//------------------------------------------------------------------------------
-(<any>UTILS).getFragment = function(str: string): DocumentFragment {
-  const temp = document.createElement("template");
-  temp.innerHTML = str;
-  return temp.content;
-};
-
-function compileValueNode(value: any, node: Element, qweb: QWeb, ctx: Context) {
-  if (value === "0" && ctx.caller) {
-    qweb._compileNode(ctx.caller, ctx);
-    return;
-  }
-
-  if (typeof value === "string") {
-    let exprID = value;
-    if (!(value in ctx.definedVariables)) {
-      exprID = `_${ctx.generateID()}`;
-      ctx.addLine(`var ${exprID} = ${ctx.formatExpression(value)};`);
-    }
-    ctx.addIf(`${exprID} || ${exprID} === 0`);
-    if (!ctx.parentNode) {
-      throw new Error("Should not have a text node without a parent");
-    }
-    if (ctx.escaping) {
-      ctx.addLine(`c${ctx.parentNode}.push({text: ${exprID}});`);
-    } else {
-      let fragID = ctx.generateID();
-      ctx.addLine(`var frag${fragID} = this.utils.getFragment(${exprID})`);
-      let tempNodeID = ctx.generateID();
-      ctx.addLine(`var p${tempNodeID} = {hook: {`);
-      ctx.addLine(
-        `  insert: n => n.elm.parentNode.replaceChild(frag${fragID}, n.elm),`
-      );
-      ctx.addLine(`}};`);
-      ctx.addLine(`var vn${tempNodeID} = h('div', p${tempNodeID})`);
-      ctx.addLine(`c${ctx.parentNode}.push(vn${tempNodeID});`);
-    }
-    if (node.childNodes.length) {
-      ctx.addElse();
-      qweb._compileChildren(node, ctx);
-    }
-    ctx.closeIf();
-    return;
-  }
-  if (value instanceof NodeList) {
-    for (let node of Array.from(value)) {
-      qweb._compileNode(<ChildNode>node, ctx);
-    }
-  }
-}
-
-QWeb.addDirective({
-  name: "esc",
-  priority: 70,
-  atNodeEncounter({ node, qweb, ctx }): boolean {
-    if (node.nodeName !== "t") {
-      let nodeID = qweb._compileGenericNode(node, ctx);
-      ctx = ctx.withParent(nodeID);
-    }
-    let value = ctx.getValue(node.getAttribute("t-esc")!);
-    compileValueNode(value, node, qweb, ctx.subContext("escaping", true));
-    return true;
-  }
-});
-
-QWeb.addDirective({
-  name: "raw",
-  priority: 80,
-  atNodeEncounter({ node, qweb, ctx }): boolean {
-    if (node.nodeName !== "t") {
-      let nodeID = qweb._compileGenericNode(node, ctx);
-      ctx = ctx.withParent(nodeID);
-    }
-    let value = ctx.getValue(node.getAttribute("t-raw")!);
-    compileValueNode(value, node, qweb, ctx);
-    return true;
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-set
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "set",
-  extraNames: ["value"],
-  priority: 60,
-  atNodeEncounter({ node, ctx }): boolean {
-    const variable = node.getAttribute("t-set")!;
-    let value = node.getAttribute("t-value")!;
-    if (value) {
-      const formattedValue = ctx.formatExpression(value);
-      if (ctx.variables.hasOwnProperty(variable)) {
-        ctx.addLine(`${ctx.variables[variable]} = ${formattedValue}`);
-      } else {
-        const varName = `_${ctx.generateID()}`;
-        ctx.addLine(`var ${varName} = ${formattedValue};`);
-        ctx.definedVariables[varName] = formattedValue;
-        ctx.variables[variable] = varName;
-      }
-    } else {
-      ctx.variables[variable] = node.childNodes;
-    }
-    return true;
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-if, t-elif, t-else
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "if",
-  priority: 20,
-  atNodeEncounter({ node, ctx }): boolean {
-    let cond = ctx.getValue(node.getAttribute("t-if")!);
-    ctx.addIf(`${ctx.formatExpression(cond)}`);
-    return false;
-  },
-  finalize({ ctx }) {
-    ctx.closeIf();
-  }
-});
-
-QWeb.addDirective({
-  name: "elif",
-  priority: 30,
-  atNodeEncounter({ node, ctx }): boolean {
-    let cond = ctx.getValue(node.getAttribute("t-elif")!);
-    ctx.addLine(`else if (${ctx.formatExpression(cond)}) {`);
-    ctx.indent();
-    return false;
-  },
-  finalize({ ctx }) {
-    ctx.closeIf();
-  }
-});
-
-QWeb.addDirective({
-  name: "else",
-  priority: 40,
-  atNodeEncounter({ ctx }): boolean {
-    ctx.addLine(`else {`);
-    ctx.indent();
-    return false;
-  },
-  finalize({ ctx }) {
-    ctx.closeIf();
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-call
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "call",
-  priority: 50,
-  atNodeEncounter({ node, qweb, ctx }): boolean {
-    if (node.nodeName !== "t") {
-      throw new Error("Invalid tag for t-call directive (should be 't')");
-    }
-    const subTemplate = node.getAttribute("t-call")!;
-    const nodeTemplate = qweb.templates[subTemplate];
-    if (!nodeTemplate) {
-      throw new Error(`Cannot find template "${subTemplate}" (t-call)`);
-    }
-    const nodeCopy = node.cloneNode(true) as Element;
-    nodeCopy.removeAttribute("t-call");
-
-    // extract variables from nodecopy
-    const tempCtx = new Context();
-    tempCtx.nextID = ctx.rootContext.nextID;
-    qweb._compileNode(nodeCopy, tempCtx);
-    const vars = Object.assign({}, ctx.variables, tempCtx.variables);
-    var definedVariables = Object.assign(
-      {},
-      ctx.definedVariables,
-      tempCtx.definedVariables
-    );
-    ctx.rootContext.nextID = tempCtx.nextID;
-
-    // open new scope, if necessary
-    const hasNewVariables = Object.keys(definedVariables).length > 0;
-    if (hasNewVariables) {
-      ctx.addLine("{");
-      ctx.indent();
-    }
-
-    // add new variables, if any
-    for (let key in definedVariables) {
-      ctx.addLine(`let ${key} = ${definedVariables[key]}`);
-    }
-
-    // compile sub template
-    const subCtx = ctx
-      .subContext("caller", nodeCopy)
-      .subContext("variables", Object.create(vars))
-      .subContext("definedVariables", Object.create(definedVariables));
-
-    qweb._compileNode(nodeTemplate.elem, subCtx);
-
-    // close new scope
-    if (hasNewVariables) {
-      ctx.dedent();
-      ctx.addLine("}");
-    }
-
-    return true;
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-foreach
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "foreach",
-  extraNames: ["as"],
-  priority: 10,
-  atNodeEncounter({ node, qweb, ctx }): boolean {
-    ctx.rootContext.shouldProtectContext = true;
-    ctx = ctx.subContext("inLoop", true);
-    const elems = node.getAttribute("t-foreach")!;
-    const name = node.getAttribute("t-as")!;
-    let arrayID = ctx.generateID();
-    ctx.addLine(`var _${arrayID} = ${ctx.formatExpression(elems)};`);
-    ctx.addLine(
-      `if (!_${arrayID}) { throw new Error('QWeb error: Invalid loop expression')}`
-    );
-    ctx.addLine(
-      `if (typeof _${arrayID} === 'number') { _${arrayID} = Array.from(Array(_${arrayID}).keys())}`
-    );
-    let keysID = ctx.generateID();
-    ctx.addLine(
-      `var _${keysID} = _${arrayID} instanceof Array ? _${arrayID} : Object.keys(_${arrayID});`
-    );
-    let valuesID = ctx.generateID();
-    ctx.addLine(
-      `var _${valuesID} = _${arrayID} instanceof Array ? _${arrayID} : Object.values(_${arrayID});`
-    );
-    ctx.addLine(`for (let i = 0; i < _${keysID}.length; i++) {`);
-    ctx.indent();
-    ctx.addLine(`context.${name}_first = i === 0;`);
-    ctx.addLine(`context.${name}_last = i === _${keysID}.length - 1;`);
-    ctx.addLine(`context.${name}_parity = i % 2 === 0 ? 'even' : 'odd';`);
-    ctx.addLine(`context.${name}_index = i;`);
-    ctx.addLine(`context.${name} = _${keysID}[i];`);
-    ctx.addLine(`context.${name}_value = _${valuesID}[i];`);
-    const nodeCopy = <Element>node.cloneNode(true);
-    let shouldWarn =
-      nodeCopy.tagName !== "t" && !nodeCopy.hasAttribute("t-key");
-    if (!shouldWarn && node.tagName === "t") {
-      if (node.hasAttribute("t-widget") && !node.hasAttribute("t-key")) {
-        shouldWarn = true;
-      }
-      if (
-        !shouldWarn &&
-        node.children.length === 1 &&
-        node.children[0].tagName !== "t" &&
-        !node.children[0].hasAttribute("t-key")
-      ) {
-        shouldWarn = true;
-      }
-    }
-    if (shouldWarn) {
-      console.warn(
-        `Directive t-foreach should always be used with a t-key! (in template: '${
-          ctx.templateName
-        }')`
-      );
-    }
-    nodeCopy.removeAttribute("t-foreach");
-    qweb._compileNode(nodeCopy, ctx);
-    ctx.dedent();
-    ctx.addLine("}");
-    return true;
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-debug
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "debug",
-  priority: 99,
-  atNodeEncounter({ ctx }) {
-    ctx.addLine("debugger;");
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-log
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "log",
-  priority: 99,
-  atNodeEncounter({ ctx, value }) {
-    const expr = ctx.formatExpression(value);
-    ctx.addLine(`console.log(${expr})`);
-  }
-});

src/qweb_extensions.ts

@@ -1,506 +0,0 @@
-import { QWeb, UTILS } from "./qweb_core";
-
-/**
- * Owl QWeb Extensions
- *
- * This file contains the implementation of non standard QWeb directives, added
- * by Owl and that will only work on Owl projects:
- *
- * - t-on
- * - t-ref
- * - t-transition
- * - t-widget/t-props/t-keepalive
- * - t-mounted
- */
-
-//------------------------------------------------------------------------------
-// t-on
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "on",
-  priority: 90,
-  atNodeCreation({ ctx, fullName, value, nodeID }) {
-    ctx.rootContext.shouldDefineOwner = true;
-    const eventName = fullName.slice(5);
-    if (!eventName) {
-      throw new Error("Missing event name with t-on directive");
-    }
-    let extraArgs;
-    let handler = value.replace(/\(.*\)/, function(args) {
-      extraArgs = args.slice(1, -1);
-      return "";
-    });
-    let error = `(function () {throw new Error('Missing handler \\'' + '${handler}' + \`\\' when evaluating template '${ctx.templateName.replace(
-      /`/g,
-      "'"
-    )}'\`)})()`;
-    if (extraArgs) {
-      ctx.addLine(
-        `p${nodeID}.on['${eventName}'] = (context['${handler}'] || ${error}).bind(owner, ${ctx.formatExpression(
-          extraArgs
-        )});`
-      );
-    } else {
-      ctx.addLine(
-        `extra.handlers['${eventName}' + ${nodeID}] = extra.handlers['${eventName}' + ${nodeID}] || (context['${handler}'] || ${error}).bind(owner);`
-      );
-      ctx.addLine(
-        `p${nodeID}.on['${eventName}'] = extra.handlers['${eventName}' + ${nodeID}];`
-      );
-    }
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-ref
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "ref",
-  priority: 95,
-  atNodeCreation({ ctx, nodeID, value, addNodeHook }) {
-    const refKey = `ref${ctx.generateID()}`;
-    ctx.addLine(`const ${refKey} = ${ctx.formatExpression(value)}`);
-    addNodeHook("create", `context.refs[${refKey}] = n.elm;`);
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-transition
-//------------------------------------------------------------------------------
-(<any>UTILS).nextFrame = function(cb: () => void) {
-  requestAnimationFrame(() => requestAnimationFrame(cb));
-};
-
-(<any>UTILS).transitionCreate = function(elm: HTMLElement, name: string) {
-  elm.classList.add(name + "-enter");
-  elm.classList.add(name + "-enter-active");
-};
-
-(<any>UTILS).transitionInsert = function(elm: HTMLElement, name: string) {
-  const finalize = () => {
-    elm.classList.remove(name + "-enter-active");
-    elm.classList.remove(name + "-enter-to");
-  };
-  this.nextFrame(() => {
-    elm.classList.remove(name + "-enter");
-    elm.classList.add(name + "-enter-to");
-    whenTransitionEnd(elm, finalize);
-  });
-};
-
-(<any>UTILS).transitionRemove = function(
-  elm: HTMLElement,
-  name: string,
-  rm: () => void
-) {
-  elm.classList.add(name + "-leave");
-  elm.classList.add(name + "-leave-active");
-  const finalize = () => {
-    elm.classList.remove(name + "-leave-active");
-    elm.classList.remove(name + "-enter-to");
-    rm();
-  };
-  this.nextFrame(() => {
-    elm.classList.remove(name + "-leave");
-    elm.classList.add(name + "-leave-to");
-    whenTransitionEnd(elm, finalize);
-  });
-};
-
-function getTimeout(delays: Array<string>, durations: Array<string>): number {
-  /* istanbul ignore next */
-  while (delays.length < durations.length) {
-    delays = delays.concat(delays);
-  }
-
-  return Math.max.apply(
-    null,
-    durations.map((d, i) => {
-      return toMs(d) + toMs(delays[i]);
-    })
-  );
-}
-
-// Old versions of Chromium (below 61.0.3163.100) formats floating pointer numbers
-// in a locale-dependent way, using a comma instead of a dot.
-// If comma is not replaced with a dot, the input will be rounded down (i.e. acting
-// as a floor function) causing unexpected behaviors
-function toMs(s: string): number {
-  return Number(s.slice(0, -1).replace(",", ".")) * 1000;
-}
-
-function whenTransitionEnd(elm: HTMLElement, cb) {
-  const styles = window.getComputedStyle(elm);
-  const delays: Array<string> = (styles.transitionDelay || "").split(", ");
-  const durations: Array<string> = (styles.transitionDuration || "").split(
-    ", "
-  );
-  const timeout: number = getTimeout(delays, durations);
-  if (timeout > 0) {
-    elm.addEventListener("transitionend", cb, { once: true });
-  } else {
-    cb();
-  }
-}
-
-QWeb.addDirective({
-  name: "transition",
-  priority: 96,
-  atNodeCreation({ ctx, value, addNodeHook }) {
-    let name = value;
-    const hooks = {
-      create: `this.utils.transitionCreate(n.elm, '${name}');`,
-      insert: `this.utils.transitionInsert(vn.elm, '${name}');`,
-      remove: `this.utils.transitionRemove(vn.elm, '${name}', rm);`
-    };
-    for (let hookName in hooks) {
-      addNodeHook(hookName, hooks[hookName]);
-    }
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-widget
-//------------------------------------------------------------------------------
-
-/**
- * The t-widget directive is certainly a complicated and hard to maintain piece
- * of code.  To help you, fellow developer, if you have to maintain it, I offer
- * you this advice: Good luck...
- *
- * Since it is not 'direct' code, but rather code that generates other code, it
- * is not easy to understand.  To help you, here  is a detailed and commented
- * explanation of the code generated by the t-widget directive for the following
- * situation:
- * ```xml
- *   <t t-widget="child" t-key="'somestring'" t-props="{flag:state.flag}"/>
- * ```
- *
- * ```js
- * // this is the virtual node representing the parent div
- * let c1 = [], p1 = { key: 1 };
- * var vn1 = h("div", p1, c1);
- *
- * // t-widget directive: we start by evaluating the expression given by t-key:
- * let key5 = "somestring";
- *
- * // We keep the index of the position of the widget in the closure.  We push
- * // null to reserve the slot, and will replace it later by the widget vnode,
- * // when it will be ready (do not forget that preparing/rendering a widget is
- * // asynchronous)
- * let _2_index = c1.length;
- * c1.push(null);
- *
- * // def3 is the deferred that will contain later either the new widget
- * // creation, or the props update...
- * let def3;
- *
- * // this is kind of tricky: we need here to find if the widget was already
- * // created by a previous rendering.  This is done by checking the internal
- * // `cmap` (children map) of the parent widget: it maps keys to widget ids,
- * // and, then, if there is an id, we look into the children list to get the
- * // instance
- * let w4 =
- *   key5 in context.__owl__.cmap
- *   ? context.__owl__.children[context.__owl__.cmap[key5]]
- *   : false;
- *
- * // we evaluate here the props given to the component. It is done here to be
- * // able to easily reference it later, and also, it might be an expensive
- * // computation, so it is certainly better to do it only once
- * let props4 = { flag: context["state"].flag };
- *
- * // If we have a widget, currently rendering, but not ready yet, and which was
- * // rendered with different props, we do not want to wait for it to be ready,
- * // then update it. We simply destroy it, and start anew.
- * if (
- *   w4 &&
- *   w4.__owl__.renderPromise &&
- *   !w4.__owl__.isStarted &&
- *   props4 !== w4.__owl__.renderProps
- * ) {
- *   w4.destroy();
- *   w4 = false;
- * }
- *
- * if (!w4) {
- *   // in this situation, we need to create a new widget.  First step is
- *   // to get a reference to the class, then create an instance with
- *   // current context as parent, and the props.
- *   let W4 = context.widgets["child"];
- *   if (!W4) {
- *     throw new Error("Cannot find the definition of widget 'child'");
- *   }
- *   w4 = new W4(owner, props4);
- *
- *   // Whenever we rerender the parent widget, we need to be sure that we
- *   // are able to find the widget instance. To do that, we register it to
- *   // the parent cmap (children map).  Note that the 'template' key is
- *   // used here, since this is what identify the widget from the template
- *   // perspective.
- *   context.__owl__.cmap[key5] = w4.__owl__.id;
- *
- *   // _prepare is called, to basically call willStart, then render the
- *   // widget
- *   def3 = w4._prepare();
- *
- *   def3 = def3.then(vnode => {
- *     // we create here a virtual node for the parent (NOT the widget). This
- *     // means that the vdom of the parent will be stopped here, and from
- *     // the parent's perspective, it simply is a vnode with no children.
- *     // However, it shares the same dom element with the component root
- *     // vnode.
- *     let pvnode = h(vnode.sel, { key: key5 });
- *
- *     // we add hooks to the parent vnode so we can interact with the new
- *     // widget at the proper time
- *     pvnode.data.hook = {
- *       insert(vn) {
- *         // the _mount method will patch the widget vdom into the elm vn.elm,
- *         // then call the mounted hooks. However, suprisingly, the snabbdom
- *         // patch method actually replace the elm by a new elm, so we need
- *         // to synchronise the pvnode elm with the resulting elm
- *         let nvn = w4._mount(vnode, vn.elm);
- *         pvnode.elm = nvn.elm;
- *       },
- *       remove() {
- *         // apparently, in some cases, it is necessary to call the destroy
- *         // method here
- *         w4.destroy();
- *       },
- *       destroy() {
- *         // and here...
- *         w4.destroy();
- *       }
- *     };
- *     // the pvnode is inserted at the correct position in the div's children
- *     c1[_2_index] = pvnode;
- *
- *     // we keep here a reference to the parent vnode (representing the
- *     // widget, so we can reuse it later whenever we update the widget
- *     w4.__owl__.pvnode = pvnode;
- *   });
- * } else {
- *   // this is the 'update' path of the directive.
- *   // the call to _updateProps is the actual widget update
- *   def3 = w4._updateProps(props4, extra.forceUpdate, extra.patchQueue);
- *   def3 = def3.then(() => {
- *     // if widget was destroyed in the meantime, we do nothing (so, this
- *     // means that the parent's element children list will have a null in
- *     // the widget's position, which will cause the pvnode to be removed
- *     // when it is patched.
- *     if (w4.__owl__.isDestroyed) {
- *       return;
- *     }
- *     // like above, we register the pvnode to the children list, so it
- *     // will not be patched out of the dom.
- *     let pvnode = w4.__owl__.pvnode;
- *     c1[_2_index] = pvnode;
- *   });
- * }
- *
- * // we register the deferred here so the parent can coordinate its patch operation
- * // with all the children.
- * extra.promises.push(def3);
- * return vn1;
- * ```
- */
-
-QWeb.addDirective({
-  name: "widget",
-  extraNames: ["props", "keepalive"],
-  priority: 100,
-  atNodeEncounter({ ctx, value, node }): boolean {
-    ctx.addLine("//WIDGET");
-    ctx.rootContext.shouldDefineOwner = true;
-    let props = node.getAttribute("t-props");
-    let keepAlive = node.getAttribute("t-keepalive") ? true : false;
-
-    // t-on- events...
-    const events: [string, string][] = [];
-    const attributes = (<Element>node).attributes;
-    for (let i = 0; i < attributes.length; i++) {
-      const name = attributes[i].name;
-      if (name.startsWith("t-on-")) {
-        events.push([name.slice(5), attributes[i].textContent!]);
-      }
-    }
-
-    let key = node.getAttribute("t-key");
-    if (key) {
-      key = ctx.formatExpression(key);
-    }
-    if (props) {
-      props = ctx.formatExpression(props);
-    }
-    let dummyID = ctx.generateID();
-    let defID = ctx.generateID();
-    let widgetID = ctx.generateID();
-    let keyID = key && ctx.generateID();
-    if (key) {
-      // we bind a variable to the key (could be a complex expression, so we
-      // want to evaluate it only once)
-      ctx.addLine(`let key${keyID} = ${key};`);
-    }
-    ctx.addLine(`let _${dummyID}_index = c${ctx.parentNode}.length;`);
-    ctx.addLine(`c${ctx.parentNode}.push(null);`);
-    ctx.addLine(`let def${defID};`);
-    let templateID = key
-      ? `key${keyID}`
-      : ctx.inLoop
-      ? `String(-${widgetID} - i)`
-      : String(widgetID);
-
-    let ref = node.getAttribute("t-ref");
-    let refExpr = "";
-    let refKey: string = "";
-    if (ref) {
-      refKey = `ref${ctx.generateID()}`;
-      ctx.addLine(`const ${refKey} = ${ctx.formatExpression(ref)}`);
-      refExpr = `context.refs[${refKey}] = w${widgetID};`;
-    }
-
-    let finalizeWidgetCode = `w${widgetID}.${
-      keepAlive ? "unmount" : "destroy"
-    }()`;
-    if (ref) {
-      finalizeWidgetCode += `;delete context.refs[${refKey}]`;
-    }
-    let createHook = "";
-    let classAttr = node.getAttribute("class");
-    let tattClass = node.getAttribute("t-att-class");
-    let styleAttr = node.getAttribute("style");
-    let tattStyle = node.getAttribute("t-att-style");
-    if (tattStyle) {
-      const attVar = `_${ctx.generateID()}`;
-      ctx.addLine(`const ${attVar} = ${ctx.formatExpression(tattStyle)};`);
-      tattStyle = attVar;
-    }
-    let updateClassCode = "";
-    if (classAttr || tattClass || styleAttr || tattStyle) {
-      let classCode = "";
-      if (classAttr) {
-        classCode =
-          classAttr
-            .split(" ")
-            .map(c => `vn.elm.classList.add('${c}')`)
-            .join(";") + ";";
-      }
-      if (tattClass) {
-        const attVar = `_${ctx.generateID()}`;
-        ctx.addLine(`const ${attVar} = ${ctx.formatExpression(tattClass)};`);
-        classCode = `for (let k in ${attVar}) {
-              if (${attVar}[k]) {
-                  vn.elm.classList.add(k);
-              }
-          }`;
-        updateClassCode = `let cl=w${widgetID}.el.classList;for (let k in ${attVar}) {if (${attVar}[k]) {cl.add(k)} else {cl.remove(k)}}`;
-      }
-      const styleExpr = tattStyle || (styleAttr ? `'${styleAttr}'` : false);
-      const styleCode = styleExpr ? `vn.elm.style = ${styleExpr}` : "";
-      createHook = `vnode.data.hook = {create(_, vn){${classCode}${styleCode}}};`;
-    }
-
-    ctx.addLine(
-      `let w${widgetID} = ${templateID} in context.__owl__.cmap ? context.__owl__.children[context.__owl__.cmap[${templateID}]] : false;`
-    );
-    ctx.addLine(`let props${widgetID} = ${props || "{}"};`);
-    ctx.addIf(
-      `w${widgetID} && w${widgetID}.__owl__.renderPromise && !w${widgetID}.__owl__.vnode && props${widgetID} !== w${widgetID}.__owl__.renderProps`
-    );
-    ctx.addLine(`w${widgetID}.destroy();`);
-    ctx.addLine(`w${widgetID} = false`);
-    ctx.closeIf();
-
-    ctx.addIf(`!w${widgetID}`);
-    // new widget
-    ctx.addLine(`let W${widgetID} = context.widgets['${value}'];`);
-
-    // maybe only do this in dev mode...
-    ctx.addLine(
-      `if (!W${widgetID}) {throw new Error(\`Cannot find the definition of widget "${value}"\`)}`
-    );
-    ctx.addLine(`w${widgetID} = new W${widgetID}(owner, props${widgetID});`);
-    ctx.addLine(
-      `context.__owl__.cmap[${templateID}] = w${widgetID}.__owl__.id;`
-    );
-    for (let [event, method] of events) {
-      ctx.addLine(`w${widgetID}.on('${event}', owner, owner['${method}'])`);
-    }
-    ctx.addLine(`def${defID} = w${widgetID}._prepare();`);
-    ctx.addLine(
-      `def${defID} = def${defID}.then(vnode=>{${createHook}let pvnode=h(vnode.sel, {key: ${templateID}, hook: {insert(vn){let nvn=w${widgetID}._mount(vnode, pvnode.elm);pvnode.elm=nvn.elm;${refExpr}},remove(){${finalizeWidgetCode}},destroy(){${finalizeWidgetCode}}}});c${
-        ctx.parentNode
-      }[_${dummyID}_index]=pvnode;w${widgetID}.__owl__.pvnode = pvnode;});`
-    );
-
-    ctx.addElse();
-    // need to update widget
-    ctx.addLine(
-      `def${defID} = w${widgetID}._updateProps(props${widgetID}, extra.forceUpdate, extra.patchQueue);`
-    );
-    let keepAliveCode = "";
-    if (keepAlive) {
-      keepAliveCode = `pvnode.data.hook.insert = vn => {vn.elm.parentNode.replaceChild(w${widgetID}.el,vn.elm);vn.elm=w${widgetID}.el;w${widgetID}.__mount();};`;
-    }
-    ctx.addLine(
-      `def${defID} = def${defID}.then(()=>{if (w${widgetID}.__owl__.isDestroyed) {return};${
-        tattStyle ? `w${widgetID}.el.style=${tattStyle};` : ""
-      }${updateClassCode}let pvnode=w${widgetID}.__owl__.pvnode;${keepAliveCode}c${
-        ctx.parentNode
-      }[_${dummyID}_index]=pvnode;});`
-    );
-    ctx.closeIf();
-
-    ctx.addLine(`extra.promises.push(def${defID});`);
-
-    if (
-      node.hasAttribute("t-if") ||
-      node.hasAttribute("t-else") ||
-      node.hasAttribute("t-elif")
-    ) {
-      ctx.closeIf();
-    }
-
-    return true;
-  }
-});
-
-//------------------------------------------------------------------------------
-// t-mounted
-//------------------------------------------------------------------------------
-QWeb.addDirective({
-  name: "mounted",
-  priority: 97,
-  atNodeCreation({ ctx, fullName, value, nodeID, addNodeHook }) {
-    ctx.rootContext.shouldDefineOwner = true;
-    const eventName = fullName.slice(5);
-    if (!eventName) {
-      throw new Error("Missing event name with t-on directive");
-    }
-    let extraArgs;
-    let handler = value.replace(/\(.*\)/, function(args) {
-      extraArgs = args.slice(1, -1);
-      return "";
-    });
-    let error = `(function () {throw new Error('Missing handler \\'' + '${handler}' + \`\\' when evaluating template '${ctx.templateName.replace(
-      /`/g,
-      "'"
-    )}'\`)})()`;
-    if (extraArgs) {
-      ctx.addLine(
-        `extra.mountedHandlers[${nodeID}] = (context['${handler}'] || ${error}).bind(owner, ${ctx.formatExpression(
-          extraArgs
-        )});`
-      );
-    } else {
-      ctx.addLine(
-        `extra.mountedHandlers[${nodeID}] = extra.mountedHandlers[${nodeID}] || (context['${handler}'] || ${error}).bind(owner);`
-      );
-    }
-    addNodeHook(
-      "insert",
-      `if (context.__owl__.isMounted) { extra.mountedHandlers[${nodeID}](); }`
-    );
-  }
-});

src/reactivity.ts

@@ -0,0 +1,144 @@
+import { getCurrent } from "./component/component_node";
+
+export function useState<T>(state: T): T {
+  const node = getCurrent()!;
+  return observe(state, () => node.render());
+}
+
+type CB = () => void;
+const observers: WeakMap<any, PSet<CB>> = new WeakMap();
+
+/**
+ * PSet (for Prototypal Set) are sets that can lookup in their "parent sets", if
+ * any.
+ */
+
+class PSet<T> extends Set<T> {
+  parent?: PSet<T>;
+
+  static createChild<T>(parent: PSet<T>): PSet<T> {
+    const pset: PSet<T> = new PSet();
+    pset.parent = parent;
+    return pset;
+  }
+
+  has(key: T): boolean {
+    if (super.has(key)) {
+      return true;
+    }
+    return this.parent ? this.parent.has(key) : false;
+  }
+
+  *[Symbol.iterator](): Generator<T> {
+    let iterator = super[Symbol.iterator]();
+    for (let elem of iterator) {
+      yield elem;
+    }
+    if (this.parent) {
+      for (let elem of this.parent) {
+        yield elem;
+      }
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+
+export function observe<T>(value: T, cb: CB): T {
+  if (isNotObservable(value)) {
+    return value;
+  }
+  if (observers.has(value)) {
+    const callbacks = observers.get(value)!;
+    callbacks.add(cb);
+    return value;
+  }
+  const callbacks: PSet<CB> = new PSet();
+  callbacks.add(cb);
+  return observeValue(value, callbacks);
+}
+
+export function unobserve<T>(value: T, cb: () => void) {
+  if (isNotObservable(value)) {
+    return;
+  }
+  if (observers.has(value)) {
+    const callbacks = observers.get(value)!;
+    callbacks.delete(cb);
+  }
+}
+
+function isNotObservable(value: any): boolean {
+  return (
+    value === null || typeof value !== "object" || value instanceof Date || value instanceof Promise
+  );
+}
+
+/**
+ * value should
+ * 1. be observable
+ * 2. not yet be observed
+ */
+function observeValue(value: any, callbacks: PSet<CB>): any {
+  const proxy = new Proxy(value as any, {
+    get(target: any, key: any): any {
+      const current = target[key];
+      if (isNotObservable(current)) {
+        return current;
+      }
+      if (observers.has(current)) {
+        // this is wrong ?
+        observers.get(current)!.parent = callbacks;
+        return current;
+      }
+      const subCallbacks = PSet.createChild(callbacks);
+      const subValue = observeValue(current, subCallbacks);
+      target[key] = subValue;
+      return subValue;
+    },
+    set(target: any, key: any, value: any): boolean {
+      // TODO: check if current !== target or proxy ??
+      const current = target[key];
+      if (current !== value) {
+        if (isNotObservable(value)) {
+          target[key] = value;
+        } else {
+          // TODO: test following scenario:
+          // 1. obj1 = observer({a:1}, somecb);
+          // 2. unobserve(obj1, somecb)
+          // 3. obj1.a = {b: 2};
+          // check that somecb was not called
+          // obj1.a.b = 3;
+          // check again that somecb was not called
+          if (observers.has(value)) {
+            const pset = observers.get(value)!;
+            pset.parent = callbacks;
+            target[key] = value;
+          } else {
+            const subCallbacks = PSet.createChild(callbacks);
+            target[key] = observeValue(value, subCallbacks);
+          }
+        }
+        notify(target);
+      }
+      return true;
+    },
+    deleteProperty(target: any, key: any) {
+      if (key in target) {
+        delete target[key];
+        notify(target);
+      }
+      return true;
+    },
+  });
+  observers.set(value, callbacks);
+  observers.set(proxy, callbacks);
+  return proxy;
+}
+
+function notify(value: any) {
+  const cbs = observers.get(value)!;
+  for (let cb of cbs) {
+    cb();
+  }
+}