up

# v2.8.1

 - [FIX] parser, code_generator: wrapped children recognition
 - [DOC] `slots` prop validation

.eslintrc

@@ -0,0 +1,47 @@
+{
+    "env": {
+        "browser": true,
+        "node": true,
+        "es2022": true
+    },
+    "parser": "@typescript-eslint/parser",
+    "plugins": ["@typescript-eslint"],
+    "parserOptions": {
+        "sourceType": "module"
+    },
+    "root": true,
+    "rules": {
+        "no-restricted-globals": ["error", "event", "self"],
+        "no-const-assign": ["error"],
+        "no-debugger": ["error"],
+        "no-dupe-class-members": ["error"],
+        "no-dupe-keys": ["error"],
+        "no-dupe-args": ["error"],
+        "no-dupe-else-if": ["error"],
+        "no-unsafe-negation": ["error"],
+        "no-duplicate-imports": ["error"],
+        "valid-typeof": ["error"],
+        "@typescript-eslint/no-unused-vars": ["error", { "vars": "all", "args": "none", "ignoreRestSiblings": false, "caughtErrors": "all" }],
+        "no-restricted-syntax": [
+            "error",
+            {
+                "selector": "MemberExpression[object.name='test'][property.name='only']",
+                "message": "test.only(...) is forbidden",
+            },
+            {
+                "selector": "MemberExpression[object.name='describe'][property.name='only']",
+                "message": "describe.only(...) is forbidden",
+            }
+        ],
+    },
+    "globals": {
+        "describe": true,
+        "expect": true,
+        "test": true,
+        "beforeEach": true,
+        "beforeAll": true,
+        "afterEach": true,
+        "afterAll": true,
+        "jest": true,
+    },
+}

.github/workflows/deploy.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x, 16.x]
+        node-version: [20.x, 22.x]
 
     steps:
     - uses: actions/checkout@v2
@@ -22,7 +22,8 @@ jobs:
       uses: actions/setup-node@v1
       with:
         node-version: ${{ matrix.node-version }}
-    - run: npm install
+    - run: npm ci
     - run: npm run test
     - run: npm run check-formatting
+    - run: npm run lint
     - run: npm run build

.gitignore

@@ -14,21 +14,22 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-package-lock.json
-yarn.lock
-
 #ide's
-.vscode
+**/.vscode/*
 .idea
 
 node_modules
 
-# Extras temp file
-/tools/owl.js
-
 release-notes.md
 
 .rpt2_cache
 
 # useful in some cases
-/temp
+/temp
+
+# owl-vision
+*/owl-vision/out/
+*/owl-vision/.vs/
+**/*.vsix
+!*/owl-vision/.vscode/launch.json
+!*/owl-vision/.vscode/tasks.json

README.md

@@ -113,6 +113,7 @@ Are you new to Owl? This is the place to start!
 - [Why did Odoo build Owl?](doc/miscellaneous/why_owl.md)
 - [Changelog (from owl 1.x to 2.x)](CHANGELOG.md)
 - [Notes on compiled templates](doc/miscellaneous/compiled_template.md)
+- [Owl devtools extension](doc/tools/devtools.md)
 
 ## Installing Owl
 
@@ -121,8 +122,28 @@ 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.4.10](https://github.com/odoo/owl/releases/tag/v1.4.10)
+- [owl](https://github.com/odoo/owl/releases/latest)
+
+## Installing Owl devtools
+
+The Owl devtools browser extension is also available in the [release](https://github.com/odoo/owl/releases/latest):
+Unzip the owl-devtools.zip file and follow the instructions depending on your browser:
+
+### Chrome
+
+Go to your chrome extensions admin panel, activate developer mode and click on `Load unpacked`.
+Select the devtools-chrome folder and that's it, your extension is active! 
+There is a convenient refresh button on the extension card (still on the same admin page) to update your code. 
+Do note that if you got some problems, you may need to completly remove and reload the extension to completly refresh the extension.
+
+### Firefox 
+Go to the address about:debugging#/runtime/this-firefox and click on `Load temporary Add-on...`.
+Select any file in the devtools-firefox folder and that's it, your extension is active! 
+Here, you can use the reload button to refresh the extension.
+
+Note that you may have to open another window or reload your tab to see the extension working.
+Also note that the extension will only be active on pages that have a sufficient version of owl.
+
 

doc/learning/tutorial_todoapp.md

@@ -174,9 +174,9 @@ class Root extends Component {
 ```
 
 The template contains a [`t-foreach`](../reference/templates.md#loops) loop to iterate
-through the tasks. It can find the `tasks` list from the component, since the
-component is the rendering context. Note that we use the `id` of each task as a
-`t-key`, which is very common. There are two css classes: `task-list` and `task`,
+through the tasks. It can find the `tasks` list from the component, since the rendering
+context contains the properties of the component. Note that we use the `id` of each task
+as a `t-key`, which is very common. There are two css classes: `task-list` and `task`,
 that we will use in the next section.
 
 Finally, notice the use of the `t-att-checked` attribute:
@@ -502,6 +502,10 @@ deleteTask(task) {
 Notice that the `onDelete` prop is defined with a `.bind` suffix: this is a special
 suffix that makes sure the function callback is bound to the component.
 
+Notice also that we have two functions named `deleteTask`. The one in the Task
+component just delegates the work to the Root component that owns the task list
+via the `onDelete` property.
+
 ## 10. Using a store
 
 Looking at the code, it is apparent that all the code handling tasks is scattered
@@ -770,10 +774,11 @@ For reference, here is the final code:
     <meta charset="UTF-8" />
     <title>OWL Todo App</title>
     <link rel="stylesheet" href="app.css" />
+  </head>
+  <body>
     <script src="owl.js"></script>
     <script src="app.js"></script>
-  </head>
-  <body></body>
+  </body>
 </html>
 ```
 

doc/readme.md

@@ -47,3 +47,4 @@ Utility/helpers:
 - [`status`](reference/component.md#status-helper): utility function to get the status of a component (new, mounted or destroyed)
 - [`validate`](reference/utils.md#validate): validates if an object satisfies a specified schema
 - [`whenReady`](reference/utils.md#whenready): utility function to execute code when DOM is ready
+- [`batched`](reference/utils.md#batched): utility function to batch function calls

doc/reference/app.md

@@ -6,6 +6,7 @@
 - [API](#api)
 - [Configuration](#configuration)
 - [`mount` helper](#mount-helper)
+- [Roots](#roots)
 - [Loading templates](#loading-templates)
 
 ## Overview
@@ -61,8 +62,13 @@ The `config` object is an object with some of the following keys:
   templates (see [translations](translations.md))
 - **`templates (string | xml document)`**: all the templates that will be used by
   the components created by the application.
+- **`getTemplate ((s: string) => Element | Function | string | void)`**: a function that will be called by owl when it
+  needs a template. If undefined is returned, owl looks into the app templates.
 - **`warnIfNoStaticProps (boolean, default=false)`**: if true, Owl will log a warning
   whenever it encounters a component that does not provide a [static props description](props.md#props-validation).
+- **`customDirectives (object)`**: if given, the corresponding function on the object will be called
+  on the template custom directives: `t-custom-*` (see [Custom Directives](templates.md#custom-directives)).
+- **`globalValues (object)`**: Global object of elements available at compilations.
 
 ## `mount` helper
 
@@ -90,6 +96,33 @@ Most of the time, the `mount` helper is more convenient, but whenever one needs
 a reference to the actual Owl App, then using the `App` class directly is
 possible.
 
+## Roots
+
+An application can have multiple roots. It is sometimes useful to instantiate
+sub components in places that are not managed by Owl, such as an html editor
+with dynamic content (the Knowledge application in Odoo).
+
+To create a root, one can use the `createRoot` method, which takes two arguments:
+
+- **`Component`**: a component class (Root component of the app)
+- **`config (optional)`**: a config object that may contain a `props` object or a
+  `env` object.
+
+The `createRoot` method returns an object with a `mount` method (same API as
+the `App.mount` method), and a `destroy` method.
+
+```js
+const root = app.createRoot(MyComponent, { props: { someProps: true } });
+await root.mount(targetElement);
+
+// later
+root.destroy();
+```
+
+Note that, like with owl `App`, it is the responsibility of the code that created
+the root to properly destroy it (before it has been removed from the DOM!). Owl
+has no way of doing it itself.
+
 ## Loading templates
 
 Most applications will need to load templates whenever they start. Here is

doc/reference/component.md

@@ -357,7 +357,7 @@ cleaning operation, since the component may be destroyed before it has even been
 mounted. The `willDestroy` hook is useful in that situation, since it is always
 called.
 
-The `onWillUnmount` hook is used to register a function that will be executed at
+The `onWillDestroy` hook is used to register a function that will be executed at
 this moment:
 
 ```javascript
@@ -451,5 +451,6 @@ console.log(status(component));
 // logs either:
 // - 'new', if the component is new and has not been mounted yet
 // - 'mounted', if the component is currently mounted
+// - 'cancelled', if the component has not been mounted yet but will be destroyed soon
 // - 'destroyed' if the component is currently destroyed
 ```

doc/reference/error_handling.md

@@ -51,8 +51,8 @@ that render its content, and a fallback if an error happened.
 ```js
 class ErrorBoundary extends Component {
   static template = xml`
-    <t t-if="error" t-slot="fallback">An error occurred</t>
-    <t t-else="" t-slot="content"`;
+    <t t-if="state.error" t-slot="fallback">An error occurred</t>
+    <t t-else="" t-slot="default"/>`;
 
   setup() {
     this.state = useState({ error: false });

doc/reference/hooks.md

@@ -112,17 +112,16 @@ of a component, rendered by Owl. It only work on a html element tagged by the
 
 ```xml
 <div>
-    <input t-ref="someDiv"/>
+    <input t-ref="someInput"/>
     <span>hello</span>
 </div>
 ```
 
-In this example, the component will be able to access the `div` and the component
-`SubComponent` with the `useRef` hook:
+In this example, the component will be able to access the `input` with the `useRef` hook:
 
 ```js
 class Parent extends Component {
-  inputRef = useRef("someComponent");
+  inputRef = useRef("someInput");
 
   someMethod() {
     // here, if component is mounted, refs are active:
@@ -139,18 +138,18 @@ The `t-ref` directive also accepts dynamic values with string interpolation
 `t-component` directives). For example,
 
 ```xml
-<div t-ref="component_{{someCondition ? '1' : '2'}}"/>
+<div t-ref="div_{{someCondition ? '1' : '2'}}"/>
 ```
 
 Here, the references need to be set like this:
 
 ```js
-this.ref1 = useRef("component_1");
-this.ref2 = useRef("component_2");
+this.ref1 = useRef("div_1");
+this.ref2 = useRef("div_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`.
+If this is not the case, accessing `el` on it will return `null`.
 
 ### `useSubEnv` and `useChildSubEnv`
 
@@ -191,12 +190,13 @@ will then be updated accordingly.
 ### `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 listener on some target whenever a component is mounted/unmounted. It takes a target
+as its first argument, forwards the other arguments to `addEventListener`. 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);
+useExternalListener(window, "click", this.closeMenu, { capture: true });
 ```
 
 ### `useComponent`
@@ -234,7 +234,8 @@ are defined by a function instead of just the dependencies.
 
 The `useEffect` hook takes two function: the effect function and the dependency
 function. The effect function perform some task and return (optionally) a cleanup
-function. The dependency function returns a list of dependencies. If any of these
+function. The dependency function returns a list of dependencies, these dependencies
+are passed as parameters in the effect function . If any of these
 dependencies changes, then the current effect will be cleaned up and reexecuted.
 
 Here is an example without any dependencies:

doc/reference/props.md

@@ -4,6 +4,7 @@
 
 - [Overview](#overview)
 - [Definition](#definition)
+- [Props comparison](#props-comparison)
 - [Binding function props](#binding-function-props)
 - [Dynamic Props](#dynamic-props)
 - [Default Props](#default-props)
@@ -56,6 +57,47 @@ the `props` object contains the following keys:
 - for `ComponentA`: `a` and `b`,
 - for `ComponentB`: `model`,
 
+## Props comparison
+
+Whenever Owl encounters a subcomponent in a template, it performs a shallow
+comparison of all props. If they are all referentially equal, then the subcomponent
+will not even be updated. Otherwise, if at least one props has changed, then
+Owl will update it.
+
+However, in some cases, we know that two values are different, but they have the
+same effect, and should not be considered different by Owl. For example, anonymous
+functions in a template are always different, but most of them should not be
+considered different:
+
+```xml
+<t t-foreach="todos" t-as="todo" t-key="todo.id">
+  <Todo todo="todo" onDelete="() => deleteTodo(todo.id)" />
+</t>
+```
+
+In that case, one can use the `.alike` suffix:
+
+```xml
+<t t-foreach="todos" t-as="todo" t-key="todo.id">
+  <Todo todo="todo" onDelete.alike="() => deleteTodo(todo.id)" />
+</t>
+```
+
+This tells Owl that this specific prop should always be considered equivalent
+(or, in other words, should be removed from the list of comparable props).
+
+Note that even if most anonymous functions should probably be considered `alike`,
+it is not necessarily true in all cases. It depends on what values are captured
+by the anonymous function. The following example shows a case where it is probably
+wrong to use `.alike`.
+
+```xml
+<t t-foreach="todos" t-as="todo" t-key="todo.id">
+  <!-- Probably wrong! todo.isCompleted may change -->
+  <Todo todo="todo" toggle.alike="() => toggleTodo(todo.isCompleted)" />
+</t>
+```
+
 ## Binding function props
 
 It is common to have the need to pass a callback as a prop. Since Owl components
@@ -95,6 +137,31 @@ class SomeComponent extends Component {
 }
 ```
 
+The `.bind` suffix also implies `.alike`, so these props will not cause additional
+renderings.
+
+## Translatable props
+
+When you need to pass a user-facing string to a subcomponent, you likely want it
+to be translated. Unfortunately, because props are arbitrary expressions, it wouldn't
+be practical for Owl to find out which parts of the expression are strings and translate
+them, and it also makes it difficult for tooling to extract these strings to generate
+terms to translate. While you can work around this issue by doing the translation in
+JavaScript, or by using `t-set` with a body (the body of `t-set` is translated),
+and passing the variable as a prop, this is a sufficiently common use case that Owl
+provides a suffix for this purpose: `.translate`.
+
+```xml
+<t t-name="ParentComponent">
+    <Child someProp.translate="some message"/>
+</t>
+```
+
+Note that the content of this attribute is _NOT_ treated as a JavaScript expression:
+it is treated as a string, as if it was an attribute on an HTML element, and translated
+before being passed to the component. If you need to interpolate some data into the
+string, you will still have to do this in JavaScript.
+
 ## Dynamic Props
 
 The `t-props` directive can be used to specify totally dynamic props:
@@ -167,6 +234,7 @@ For each key, a `prop` definition is either a boolean, a constructor, a list of
   - `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,
+  - `values`: if the type was `Object`, then the `values` key describes the interface of values in the object, this allows validating objects that are used as mappings, where keys are not known in advance but the shape of the values is.
   - `validate`: this is a function which should return a boolean to determine if
     the value is valid or not. Useful for custom validation logic.
   - `optional`: if true, the prop is not mandatory
@@ -192,7 +260,7 @@ class ComponentB extends owl.Component {
     count: {type: Number},
     messages: {
       type: Array,
-      element: {type: Object, shape: {id: Boolean, text: String }
+      element: {type: Object, shape: {id: Boolean, text: String }}
     },
    date: Date,
    combinedVal: [Number, Boolean],
@@ -230,7 +298,12 @@ class ComponentB extends owl.Component {
         id: Number,
         name: {type: String, optional: true},
         url: String
-      ]},    // object, with keys id (number), name (string, optional) and url (string)
+      }
+    },  // object, with keys id (number), name (string, optional) and url (string)
+    someObj3: {
+      type: Object,
+      values: { type: Array, element: String },
+    }, // object with arbitary keys where values are arrays of strings
     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
@@ -247,6 +320,28 @@ class ComponentB extends owl.Component {
 
 Note: the props validation code is done by using the [validate utility function](utils.md#validate).
 
+### `slots` prop
+
+If a component that uses [slots](slots.md) also lists or validates its props, then
+you will have to explicitely allow the `slots` prop (with an `Object` type), or
+allow extra props using the `*` notation mentioned above. This is because slots
+are provided to a component [as props](slots.md#slots-and-props).
+
+For example:
+
+```js
+class MyComponent extends Component {
+  static props = [someProp, slots?];
+}
+
+class MyComponentWithValidation extends Component {
+  static props = {
+    someProp: {type: Number, optional: true},
+    slots : {type: Object, optional: true},
+  }
+}
+```
+
 ## Good Practices
 
 A `props` object is a collection of values that come from the parent. As such,

doc/reference/reactivity.md

@@ -2,130 +2,394 @@
 
 ## Content
 
-- [Overview](#overview)
+- [Introduction](#introduction)
 - [`useState`](#usestate)
 - [`reactive`](#reactive)
-- [`markRaw`](#markraw)
-- [`toRaw`](#toraw)
+- [`Escape hatches`](#escape-hatches)
+- [`Advanced usage`](#advanced-usage)
 
-## Overview
+## Introduction
 
 Reactivity is a big topic in javascript frameworks. The goal is to provide a
-simple way to manipulate state, in such a way that the interface automatically
-update accordingly to state changes. Also, we obviously want this to happen in
-a performant way.
+simple way to manipulate state, in such a way that the interface updates automatically
+according to state changes, and to do so in a performant manner.
 
-To solve this issue, Owl provides two reactivity primitives:
-
-- `reactive`, which returns a proxy to its first argument, and tracks all read/update
-  operation going through it,
-- `useState`: a hook, that internally uses `reactive`, and is linked to its
-  owner component: any read operation will be tracked (key by key), and any
-  updates to these tracked values will cause the component to be rerendered.
-
-Most of the time, the `useState` hook is the best solution.
-
-Since version 2.0, Owl applies the fine grained reactivity at the component
-level: reactive objects received as props are automatically subscribed to by the
-component, so Owl can track which part of these props are consumed by each
-component, and is therefore able to only rerender the impacted components.
+To this end, Owl provides a proxy-based reactivity system, based on the `reactive` primitive.
+The `reactive` function takes an object as a first argument, and an optional callback as its second
+argument, it returns a proxy of the object. This proxy tracks what properties are read
+through the proxy, and calls the provided callback whenever one of these properties is changed
+through any reactive version of the same object. It does so in depth, by returning reactive versions
+of the subobjects when they are read.
 
 ## `useState`
 
-Let us start by an example of how `useState` could be used:
+While the `reactive` primitive is very powerful, its usage in components follow a very standard pattern:
+components want to be rerendered when part of the state which they depend on for rendering changes. To
+this end, owl provides a standard hook: `useState`. To put it simply, this hook simply calls reactive
+with the provided object, and the current component's render function as its callback. This will cause
+it to rerender whenever any part of the state object that has been read by this component is modified.
+
+Here is a simple example of how `useState` can be used:
 
 ```js
 class Counter extends Component {
   static template = xml`
-    <div t-on-click="increment">
+    <div t-on-click="() => this.state.value++">
       <t t-esc="state.value"/>
     </div>`;
 
   setup() {
     this.state = useState({ value: 0 });
   }
+}
+```
 
-  increment() {
-    this.state.value++;
+This component reads `state.value` when it renders, subscribing it to changes to that key. Whenever
+the value changes, Owl will update the component. Note that there is nothing special about the
+`state` property, you can name your state variables whatever you want, and you can have multiple of
+them on the same component if it makes sense to do so. This also allows `useState` to be used in custom
+hooks that may require state that is specific to that hook.
+
+### Reactive props
+
+Since version 2.0, Owl renders are no longer "deep" by default: a component is only rerendered by its
+parent if its props have changed (using a simple equality test). What if the contents of a props have
+changed in a deeper property? If that prop is reactive, owl will rerender the child components that
+need to be updated automatically, and only those components, it does so by reobserving reactive
+objects passed as props to components. Consider the following example:
+
+```js
+class Counter extends Component {
+  static template = xml`
+    <div t-on-click="() => props.state.value++">
+      <t t-esc="props.state.value"/>
+    </div>`;
+}
+
+class Parent extends Component {
+  static template = xml`
+    <Counter state="this.state"/>
+    <button t-on-click="() => this.state.value = 0">Reset counter</button>
+    <button t-on-click="() => this.state.test++" t-esc="this.state.test"/>`;
+
+  setup() {
+    this.state = useState({ value: 0, test: 1 });
   }
 }
 ```
 
-If one were to use a simple state object, Owl would not be aware that the value
-was changed and that the component should be rerendered. With the `useState`
-hook, `this.state` is now a reactive object, so this component works as expected.
+When clicking on the counter button, only the Counter rerenders, because the Parent has never read
+the "value" key in the state. When clicking on the "Reset Counter" button, the same thing happens:
+only the Counter component rerenders. What matters is not _where_ the state is updated, but which
+parts of the state are updated, and which components depend on them. This is achieved by Owl by
+automatically calling `useState` on reactive objects passed as props to a child component.
+
+When clicking on the last button, the parent is rerendered, but the child does not care about the
+`test` key: it has not read it. The props that we give it (`this.state`) have also not changed,
+as such, the parent updates but the child doesn't.
+
+For most day-to-day operations, `useState` should cover all of your needs. If
+you are curious about more advanced use cases and technical details, read on.
+
+### Debugging subscriptions
+
+Owl provides a way to show which reactive objects and keys a component is subscribed to: you can
+look at `component.__owl__.subscriptions`. Note that this is on the internal `__owl__` field, and
+should not be used in any type of production code as the name of this property or any of its properties
+or methods are subject to change at any point, even in stable versions of Owl, and may become available
+only in debug mode in the future.
 
 ## `reactive`
 
 The `reactive` function is the basic reactivity primitive. It takes an object
 or an array as first argument, and optionally, a function as the second argument.
-The function will be called whenever any tracked value is updated.
+The function is called whenever any tracked value is updated.
 
 ```js
 const obj = reactive({ a: 1 }, () => console.log("changed"));
 
-obj.a = 2; // does not log anything: the 'a' key was not read
-console.log(obj.a); // log 2, and reads the 'a' key => it is now tracked
-obj.a = 3; // log 'changed' because we updated a tracked value
+obj.a = 2; // does not log anything: the 'a' key has not been read yet
+console.log(obj.a); // logs 2 and reads the 'a' key => it is now tracked
+obj.a = 3; // logs 'changed' because we updated a tracked value
 ```
 
 An important property of reactive objects is that they can be reobserved: this
-will create an independant proxy that tracks another set of keys:
+will create an independent proxy that tracks another set of keys:
 
 ```js
 const obj1 = reactive({ a: 1, b: 2 }, () => console.log("observer 1"));
 const obj2 = reactive(obj1, () => console.log("observer 2"));
 
-console.log(obj1.a); // log 1, and reads the 'a' key => it is now tracked by observer 1
-console.log(obj1.b); // log 2, and 'b' is now tracked by observer 1
-console.log(obj2.b); // log 2, and 'b' is now tracked by observer 1
-obj2.a = 3; // log 'observer1', because observer2 does not track a
-obj2.b = 3; // log 'observer1' and 'observer2'
+console.log(obj1.a); // logs 1, and reads the 'a' key => it is now tracked by observer 1
+console.log(obj2.b); // logs 2, and 'b' is now tracked by observer 2
+obj2.a = 3; // only logs 'observer1', because observer2 does not track a
+obj2.b = 3; // only logs 'observer2', because observer1 does not track b
+console.log(obj2.a, obj1.b); // logs 3 and 3, while the object is observed independently, it is still a single object
 ```
 
-Obviously, one can use `reactive` on the result of a `useState` if wanted, this
-is the proper way to watch for some state changes.
+Because `useState` returns a normal reactive object, it is possible to call `reactive` on the result
+of a `useState` to observe changes to that object while outside the context of a component, or to
+call `useState` on reactive objects created outside of components. In those cases, one needs to be
+careful with regards to the lifetime of those reactive objects, as holding references to these
+objects may prevent garbage collection of the component and its data even if Owl has destroyed it.
 
-## `markRaw`
+### Subscriptions are ephemereal
 
-Marks an object so that it is ignored by the reactivity system. This function returns its argument.
+Subscription to state changes are ephemereal, whenever an observer is notified that a state object
+has changed, all of its subscriptions are cleared, meaning that if it still cares about it, it
+should read the properties it cares about again. For example:
 
 ```js
-const someObject = markRaw(...);
+const obj = reactive({ a: 1 }, () => console.log("observer called"));
+
+console.log(obj.a); // logs 1, and reads the 'a' key => it is now tracked by the observer
+obj.a = 3; // logs 'observer1' and clears the subscriptions of the observer
+obj.a = 4; // doesn't log anything, the key is no longer observed
+```
+
+This may seem counter-intuitive, but it makes perfect sense in the context of components:
+
+```js
+class DoubleCounter extends Component {
+  static template = xml`
+    <t t-esc="'selected: ' + state.selected + ', value: ' + state[state.selected]"/>
+    <button t-on-click="() => this.state.count1++">increment count 1</button>
+    <button t-on-click="() => this.state.count2++">increment count 2</button>
+    <button t-on-click="changeCounter">Switch counter</button>
+  `;
+
+  setup() {
+    this.state = useState({ selected: "count1", count1: 0, count2: 0 });
+  }
+
+  changeCounter() {
+    this.state.selected = this.state.selected === "count1" ? "count2" : "count1";
+  }
+}
+```
+
+In this component, if we increment the value of the second counter, the component will not rerender,
+which makes sense as rerendering will have no effect, as the second counter is not displayed. If we
+toggle the component to display the second counter, we now no longer want the component to rerender
+when the value of the first counter changes, and this is what happens: a component only rerenders
+when there are changes to pieces of state that have been read during or after the previous render.
+If a piece of state has not been read in the last render, we know that its value won't influence the
+rendered output, and so we can ignore it.
+
+### reactive `Map` and `Set`
+
+The reactivity system has special support built-in for the standard container types `Map` and `Set`.
+They behave like one would expect: reading a key subscribes the observer to that key, adding or
+removing an item to them notifies observers that have used any of the iterators on that reactive
+object, such as `.entries()` or `.keys()`, likewise with clearing them.
+
+## Escape hatches
+
+Sometimes, it is desirable to bypass the reactivity system. Creating proxies when interacting with
+reactive objects is expensive, and while on the whole, the performance benefit that we get by
+rerendering only the parts of the interface that need it outweighs that cost, in some cases, we want
+to be able to opt out of creating them in the first place. This is the purpose of `markRaw`:
+
+### `markRaw`
+
+Marks an object so that it is ignored by the reactivity system, meaning that if this object is ever
+part of a reactive object, it will be returned as is, and no keys in that object will be
+observed.
+
+```js
+const someObject = markRaw({ b: 1 });
 const state = useState({
   a: 1,
-  obj: someObject
+  obj: someObject,
 });
-// here, state.obj === someObject
+console.log(state.obj.b); // attempt to subscribe to the "b" key in someObject
+state.obj.b = 2; // No rerender will occur here
+console.log(someObject === state.obj); // true
 ```
 
-This is useful in some rare cases. For example, some complex and large object such
-that going through the reactivity system may cause a non trivial performance slowdown.
+This is useful in some rare cases. One such example would be if you want to use an array of objects
+that is potentially large to render a list, but those objects are known to be immutable:
+
+```js
+this.items = useState([
+  { label: "some text", value: 42 },
+  // ... 1000 total objects
+]);
+```
+
+in the template:
+
+```xml
+<t t-foreach="items" t-as="item" t-key="item.label" t-esc="item.label + item.value"/>
+```
+
+Here, on every render, we go and read one thousand keys from a reactive object, which causes
+one thousand reactive objects to be created. If we know that the content of these objects
+cannot change, this is wasted work. If instead all of these objects are marked as raw, we avoid
+all of this work while keeping the ability to lean on the reactivity to track the presence and
+identity of these objects:
+
+```js
+this.items = useState([
+  markRaw({ label: "some text", value: 42 }),
+  // ... 1000 total objects
+]);
+```
 
 However, use this function with caution: this is an escape hatch from the reactivity
-system, and as such, using it may cause subtle and unintended issues!
-
-## `toRaw`
-
-Given a reactive object, this function returns the underlying, non-reactive,
-corresponding object.
+system, and as such, using it may cause subtle and unintended issues! For example:
 
 ```js
-// in setup
-const state = useState({ value: 1 });
+// This will cause a rerender
+this.items.push(markRaw({ label: "another label", value: 1337 }));
 
-// later:
-const rawState = toRaw(this.state);
-rawState.value = 3; // will NOT be picked up by the reactivity system!!!
+// THIS WILL NOT CAUSE A RENDER!
+this.items[17].value = 3;
+// The UI is now desynced from component's state until the next render caused by something else
 ```
 
-Here again, this is useful in some situations where we want to explicitely bypass
-Owl, but using this function means that the responsability of coordinating
-state update is given to the user code, instead of Owl. Subtle bugs may arise!
+In short: only use `markRaw` if your application is slowing down noticeably and profiling reveals
+that a lot of time is spent creating useless reactive objects.
 
-Also, normal (non-reactive objects) will be directly returned by `toRaw`:
+### `toRaw`
+
+While `markRaw` marks an object so that it is never made reactive, `toRaw` takes an object and
+returns the underlying non-reactive object. It can be useful in some niche cases. In particular,
+because the reactivity system returns a proxy, the returned object does not compare equal to the
+original object:
 
 ```js
-const obj = { a: 1 };
-console.log(toRaw(obj) === obj); // true
+const obj = {};
+const reactiveObj = reactive(obj);
+console.log(obj === reactiveObj); // false
+console.log(obj === toRaw(reactiveObj)); // true
 ```
+
+It can also be useful during debugging, as unfolding proxies recursively in debuggers can be confusing.
+
+## Advanced usage
+
+The following is a collection of small snippets that leverage the reactivity system in
+"non-standard" ways to help you understand its power and where using it might make your code simpler.
+
+### Notification manager
+
+Showing notifications is a pretty common need in web applications, you may want to show a
+notification from any other component within the application, and the notifications should stack on
+top of one another regardless of which component spawned them, here is how we can leverage the
+reactivity to accomplish this:
+
+```js
+let notificationId = 1;
+const notifications = reactive({});
+class NotificationContainer extends Component {
+  static template = xml`
+    <t t-foreach="notifications" t-as="notification" t-key="notification_key" t-esc="notification"/>
+  `;
+  setup() {
+    this.notifications = useState(notifications);
+  }
+}
+
+export function addNotification(label) {
+  const id = notificationId++;
+  notifications[id] = label;
+  return () => {
+    delete notifications[id];
+  };
+}
+```
+
+Here, the `notifications` variable is a reactive object. Notice how we didn't give `reactive` a
+callback: this is because in this case, all we care about is that adding or removing notifications
+in the `addNotification` function goes through the reactivity system. The `NotificationContainer`
+component reobserves this object with `useState`, and is updated whenever notifications are
+added or removed.
+
+### Store
+
+Centralizing application state is a pretty common want/need in web applications. Because of the way
+the reactivity system works, you can treat any reactive object as a store, and if you call `useState`
+on it, components automatically observe only the part of the store that they're interested in:
+
+```js
+export const store = reactive({
+  list: [],
+  add(item) {
+    this.list.push(item);
+  },
+});
+
+export function useStore() {
+  return useState(store);
+}
+```
+
+In any component:
+
+```js
+import { useStore } from "./store";
+
+class List extends Component {
+  static template = xml`
+    <t t-foreach="store.list" t-as="item" t-key="item" t-esc="item"/>
+  `;
+  setup() {
+    this.store = useStore();
+  }
+}
+```
+
+Anywhere in the application:
+
+```js
+import { store } from "./store";
+// Will cause any instance of the List component in the app to update
+store.add("New list item!");
+```
+
+Notice how we can make objects with methods into reactive objects, and when these methods are used
+to mutate the store contents, it works as expected. And while stores are generally one-off objects,
+it is entirely possible to make class instances reactive:
+
+```js
+class Store {
+  list = [];
+  add(item) {
+    this.list.push(item);
+  }
+}
+// Essentially equivalent to the previous code
+export const store = reactive(new Store());
+```
+
+Which can be useful to unit test the class separately.
+
+### Local storage synchronization
+
+Sometimes, you want to persist some state accross reloads, you can do this by storing it in the
+`localStorage`, but what if you want to update the `localStorage` item every time the state changes,
+so that you don't have to manually synchronize the states? Well, you can use the reactivity system
+to write a custom hook that will do that for you:
+
+```js
+function useStoredState(key, initialState) {
+  const state = JSON.parse(localStorage.getItem(key)) || initialState;
+  const store = (obj) => localStorage.setItem(key, JSON.stringify(obj));
+  const reactiveState = reactive(state, () => store(reactiveState));
+  store(reactiveState);
+  return useState(state);
+}
+
+class MyComponent extends Component {
+  setup() {
+    this.state = useStoredState("MyComponent.state", { value: 1 });
+  }
+}
+```
+
+One important thing to notice is that both times we call `store`, we call it with `reactiveState`,
+not `state`: we need `store` to read the keys through a reactive object for it to correctly
+subscribe to state changes. Notice also that we call `store` the first time by hand, as otherwise it
+will not be subscribed to anything, and no amount of change in the object will cause the reactive
+callback to be invoked.

doc/reference/slots.md

@@ -133,7 +133,7 @@ Slots can define a default content, in case the parent did not define them:
 ## Dynamic Slots
 
 The `t-slot` directive is actually able to use any expressions, using string
-interplolation:
+interpolation:
 
 ```xml
  <t t-slot="{{current}}" />
@@ -175,7 +175,7 @@ class Notebook extends Component {
     <div class="notebook">
       <div class="tabs">
         <t t-foreach="tabNames" t-as="tab" t-key="tab_index">
-          <span t-att-class="{active:tab_index === activeTab}" t-on-click="() => state.activeTab=tab">
+          <span t-att-class="{active:tab_index === activeTab}" t-on-click="() => state.activeTab=tab_index">
             <t t-esc="props.slots[tab].title"/>
           </span>
         </t>
@@ -201,16 +201,17 @@ use this `Notebook` component:
 
 ```xml
 <Notebook>
-  <t t-set-slot="page1" title="'Page 1'">
+  <t t-set-slot="page1" title.translate="Page 1">
     <div>this is in the page 1</div>
   </t>
-  <t t-set-slot="page2" title="'Page 2'" hidden="somevalue">
+  <t t-set-slot="page2" title.translate="Page 2" hidden="somevalue">
     <div>this is in the page 2</div>
   </t>
 </Notebook>
 ```
 
-Slot params works like normal props, so one can use the `.bind` suffix to
+Slot params works like normal props, so one can use suffixes like `.translate`
+when a prop is a user facing string and should be translated, or `.bind` to
 bind a function if needed.
 
 ## Slot scopes

doc/reference/templates.md

@@ -18,6 +18,7 @@
   - [Sub Templates](#sub-templates)
   - [Dynamic Sub Templates](#dynamic-sub-templates)
   - [Debugging](#debugging)
+  - [Custom Directives](#custom-directives)
 - [Fragments](#fragments)
 - [Inline templates](#inline-templates)
 - [Rendering svg](#rendering-svg)
@@ -55,17 +56,19 @@ extensions.
 
 For reference, here is a list of all standard QWeb directives:
 
-| Name                           | Description                                                     |
-| ------------------------------ | --------------------------------------------------------------- |
-| `t-esc`                        | [Outputting safely a value](#outputting-data)                   |
-| `t-out`                        | [Outputting value, possibly 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](#sub-templates)                       |
-| `t-debug`, `t-log`             | [Debugging](#debugging)                                         |
-| `t-translation`                | [Disabling the translation of a node](translations.md)          |
+| Name                           | Description                                                             |
+| ------------------------------ | ----------------------------------------------------------------------- |
+| `t-esc`                        | [Outputting safely a value](#outputting-data)                           |
+| `t-out`                        | [Outputting value, possibly 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](#sub-templates)                               |
+| `t-debug`, `t-log`             | [Debugging](#debugging)                                                 |
+| `t-translation`                | [Disabling the translation of a node](translations.md)                  |
+| `t-translation-context`        | [Context of translations within a node](translations.md)                |
+| `t-translation-context-*`      | [Context of translation for a specific node attribute](translations.md) |
 
 The component system in Owl requires additional directives, to express various
 needs. Here is a list of all Owl specific directives:
@@ -80,6 +83,7 @@ needs. Here is a list of all Owl specific directives:
 | `t-slot`, `t-set-slot`, `t-slot-scope` | [Rendering a slot](slots.md)                                    |
 | `t-model`                              | [Form input bindings](input_bindings.md)                        |
 | `t-tag`                                | [Rendering nodes with dynamic tag name](#dynamic-tag-names)     |
+| `t-custom-*`                           | [Rendering nodes with custom directives](#custom-directives)    |
 
 ## QWeb Template Reference
 
@@ -115,7 +119,7 @@ It is useful to explain the various rules that apply on these expressions:
    <div><p t-if="console.log(1)">NOT valid</p></div>
    ```
 
-2. it can use anything in the rendering context (typically, the component):
+2. it can use anything in the rendering context (which typically contains the properties of the component):
 
    ```xml
    <p t-if="user.birthday === today()">Happy bithday!</p>
@@ -189,6 +193,15 @@ The first `t-out` will act as a `t-esc` directive, which means that the content
 of `value1` will be escaped. However, since `value2` has been tagged as a markup,
 this will be injected as html.
 
+`markup` can also be used as a tag function, allowing the interpolated values to
+be safely escaped:
+
+```js
+const maliciousInput = "<script>alert('💥💥')</script>";
+// <b>&lt;script&gt;alert(&#x27;💥💥&#x27;)&lt;/script&gt;</b>
+const value = markup`<b>${maliciousInput}</b>`;
+```
+
 ### 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, ...
@@ -376,15 +389,16 @@ An important difference should be made with the usual `QWeb` behaviour: Owl
 requires the presence of a `t-key` directive, to be able to properly reconcile
 renderings.
 
-`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).
+`t-foreach` can iterate on any iterable, and also has special support for objects
+and maps, it will expose the key of the current iteration as the contents of the
+`t-as`, and the corresponding value with the same name and the suffix `_value`.
 
-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`):
+In addition to the name passed via t-as, `t-foreach` provides a few other useful
+variables (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_value`: the current iteration value, identical to `$as` for arrays and
+  other iterables, but for objects and maps, 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`)
@@ -477,7 +491,7 @@ 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>
+<t t-foreach="[...items]" t-as="item">...</t>
 ```
 
 The `...` operator will convert the `Set` (or any other iterables) into a list,
@@ -541,9 +555,8 @@ This can be used to define variables scoped to a sub template:
 ```
 
 Note: by default, the rendering context for a sub template is simply the current
-rendering context (so, the current component). However, it may be useful to be
-able to specify a specific object as context. This can be done by using the
-`t-call-context` directive:
+rendering context. However, it may be useful to be able to specify a specific
+object as context. This can be done by using the `t-call-context` directive:
 
 ```xml
 <t t-call="other-template" t-call-context="obj"/>
@@ -588,6 +601,35 @@ will stop execution if the browser dev tools are open.
 
 will print 42 to the console.
 
+### Custom Directives
+
+Owl 2 supports the declaration of custom directives. To use them, an Object of functions needs to be configured on the owl APP:
+
+```js
+ new App(..., {
+    customDirectives: {
+     test_directive: function (el, value) {
+            el.setAttribute("t-on-click", value);
+       }
+   }
+  });
+```
+
+The functions will be called when a custom directive with the name of the
+function is found. The original element will be replaced with the one
+modified by the function.
+This :
+
+```xml
+<div t-custom-test_directive="click" />
+```
+
+will be replaced by :
+
+```xml
+<div t-on-click="value"/>
+```
+
 ## Fragments
 
 Owl 2 supports templates with an arbitrary number of root elements, or even just

doc/reference/translations.md

@@ -1,17 +1,28 @@
 # 🦉 Translations 🦉
 
 If properly setup, Owl can translate all rendered templates. To do
-so, it needs a translate function, which takes a string and returns a string.
+so, it needs a translate function, which takes
+
+- a string (the term to translate)
+- a string (the translation context of the term)
+  and returns a string.
 
 For example:
 
 ```js
 const translations = {
-  hello: "bonjour",
-  yes: "oui",
-  no: "non",
+  fr: {
+    hello: "bonjour",
+    yes: "oui",
+    no: "non",
+  },
+  pt: {
+    hello: "bom dia",
+    yes: "sim",
+    no: "não",
+  },
 };
-const translateFn = (str) => translations[str] || str;
+const translateFn = (str, ctx) => translations[ctx]?.[str] || str;
 
 const app = new App(Root, { templates, tranaslateFn });
 // ...
@@ -27,6 +38,11 @@ Once setup, all rendered templates will be translated using `translateFn`:
   `placeholder`, `label` and `alt`,
 - translating text nodes can be disabled with the special attribute `t-translation`,
   if its value is `off`.
+- the translate function receives as second parameter a context that can be used
+  to contextualized the translation. That context can be set globally on a node
+  and its children by using `t-translation-context`. If a specific node
+  attribute `x` needs another context, that context can be specified with a
+  special directive `t-translation-context-x`.
 
 So, with the above `translateFn`, the following templates:
 
@@ -46,6 +62,22 @@ will be rendered as:
 <input placeholder="bonjour" other="yes"/>
 ```
 
+and the following template:
+
+```xml
+<div t-translation-context="fr" title="hello">hello</div>
+<div>Are you sure?</div>
+<input t-translation-context-placeholder="pt" placeholder="hello" other="yes"/>
+```
+
+will be rendered as:
+
+```xml
+<div title="bonjour">bonjour</div>
+<div>Are you sure?</div>
+<input placeholder="bom dia" other="yes"/>
+```
+
 Note that the translation is done during the compilation of the template, not
 when it is rendered.
 

doc/reference/utils.md

@@ -9,6 +9,7 @@ functions are all available in the `owl.utils` namespace.
 - [`loadFile`](#loadfile): loading a file (useful for templates)
 - [`EventBus`](#eventbus): a simple EventBus
 - [`validate`](#validate): a validation function
+- [`batched`](#batched): batch function calls
 
 ## `whenReady`
 
@@ -78,3 +79,22 @@ validate(
 //    - 'id' is missing (should be a number),
 //    - 'url' is missing (should be a boolean or list of numbers),
 ```
+
+## `batched`
+
+The `batched` function creates a batched version of a callback so that multiple calls to it within the same microtick will only result in a single invocation of the original callback.
+
+```js
+function hello() {
+  console.log("hello");
+}
+
+const batchedHello = batched(hello);
+batchedHello();
+// Nothing is logged
+batchedHello();
+// Still not logged
+
+await Promise.resolve(); // Await the next microtick
+// "hello" is logged only once
+```

doc/tools/devtools.md

@@ -0,0 +1,56 @@
+# Owl Devtools Browser extension
+
+The owl devtools browser extension is an extension available on chrome or firefox which adds an owl tab
+to the browser devtools in order to inspect all owl apps that are present on any web page, their components
+and allows to interract with their data to a certain extend. There is also a profiler available to visualize
+the components' lifecycle and be able to trace their origin.
+
+See the [`devtools doc`](devtools_guide.md) for more information.
+
+## Install the extension manually (for devs)
+
+In the owl root folder:
+
+```bash
+npm install
+```
+
+For chrome:
+
+```bash
+npm run build:devtools-chrome
+```
+
+For firefox:
+
+```bash
+npm run build:devtools-firefox
+```
+
+You can also run:
+
+```bash
+npm run dev:devtools-chrome
+```
+
+or
+
+```bash
+npm run dev:devtools-firefox
+```
+
+to avoid recompiling owl and gain time if it has already been done.
+
+To run the extension:
+
+In google chrome: go to your chrome extensions admin panel, activate developer mode and click on `Load unpacked`.
+Select the output folder (dist/devtools) and that's it, your extension is active!
+There is a convenient refresh button on the extension card (still on the same admin page) to update your code.
+Do note that if you got some problems, you may need to completly remove and reload the extension to completly refresh the extension.
+
+In firefox: go to the address about:debugging#/runtime/this-firefox and click on `Load temporary Add-on...`.
+Select any file of the output folder (dist/devtools) and that's it, your extension is active!
+Here, you can use the reload button to refresh the extension.
+
+Note that you may have to open another window or reload your tab to see the extension working.
+Also note that the extension will only be active on pages that have a sufficient version of owl.

doc/tools/devtools_guide.md

@@ -0,0 +1,171 @@
+# Owl Devtools Guide
+
+## Information popup
+
+After having installed the extension, a new icon will be added to your extension bar.
+If you don't see it, you can pin the extension using the extensions popup.
+
+<img src="screenshots/extensions.png"/>
+
+Clicking on the owl icon will open the information popup. This popup is useful
+to know in advance whether owl is loaded in the tab or not. This is also indicated
+by the icon itself: if it is flipped upside-down, it means that owl is not loaded in the
+active tab. Do note that old versions of owl are not supported by the extension and will
+therefore be indicated either as obsolete or absent by the extension popup.
+
+<img src="screenshots/popup.png"/>
+
+## First steps
+
+When you are on a page where owl is detected, you can open your devtools either with
+right-click -> Inspect or using F12. In the devtools menu, you can search for the Owl
+tab which is added by the extension. It will be present by default at the end of the list but
+you can drag and drop it at the position you want for easier navigation in the future.
+
+<img src="screenshots/find_owl_tab.png"/>
+
+When you open the tab, you arrive on the Components view by default which is one of the
+two available tabs at the top. Here is an example of the devtools on the Odoo CRM app:
+
+<img src="screenshots/crm.png"/>
+
+## Components tab
+
+The components tab is separated into two sub windows: the components tree in the left and
+the component details in the right. The components tree will display all the different
+components that are present in the tab in the form of a tree. The root of this tree is
+actually the app which is not a component but can still be inspected by the devtools like
+one. There can also be multiple apps loaded in the page like in website:
+
+<img src="screenshots/multi_apps.png"/>
+
+There is a convenient search bar at the top of the components tree which will help finding
+the components tou want in the tree and also, an element picker can be used to directly select
+the component you want to focus on in the page which is especially useful when 1trying to find
+what you want. Just click on the elements picker icon and click on the element you want to focus
+on in the page and it will be selected in the devtools accordingly. Hovering any element in the
+page in this mode will highlight it and the same happens anytime in the components tree.
+
+<img src="screenshots/picker.png"/>
+
+In the tree itself, the navigation is quite simple and is similar to the one in the Elements tab
+of the browser's devtools. It is possible to navigate with the keyboard using the arrow keys and
+multiple shortcuts are available in a custom menu when right-clicking on a component. This menu
+allows to expand/fold all the children nodes of a component, fold its direct children only, inspect
+the source code of the component, send it as a global variable in the console, go to the Elements tab
+and focus on its content, force a rerender of the component, send its observed states to the console
+as a global variable, inspect its compiled template in the Sources tab or send its raw template
+to the console.
+
+<img src="screenshots/menu.png"/>
+
+The component details window in the right will show the component that is currently selected as well
+as its env, props, observed states and all the other variables that are present on its instance.
+While the props and the env are already present on the actual instance of the component and are
+pretty explicit by themselves, the observed state value is a bit more complicated to grasp.
+
+The observed state is actually information about which variables are being observed by the component:
+when any property of a reactive object is being read by the component, the component will subscribe
+to this property which means it will listen to any change that can occur on the property and render
+when such a change occurs. This can be visualized easily within the devtools inside of the observed
+state section: observed properties of the reactive object(s) are displayed in bold while the others
+are greyed out. Do keep in mind that a greyed out property in the observed state of one component
+may be observed by another and the other way around is also possible. Here is an example for some
+user Field component:
+
+<img src="screenshots/states.png"/>
+
+Navigation inside the properties is also similar to the one in console variables: properties have
+their prototype displayed and getters will get their value when clicked on (...). It is also possible to
+send any property to the console using the right-click context menu on it and functions can be inspected
+in the sources tab as well.
+
+<img src="screenshots/function_menu.png"/>
+
+Using the right-click context menu on a property also allows to observe variables. Observed variables will
+be sent to a dedicated section of the details window and their value will be refreshed every 200ms. These
+variables are only shown when they are found and their access path will be kept in memory inside the
+browser so that it will always persist until the user decides to stop observing the variable. As in the
+browser's devtools, observed objects are displayed in reduced form and cannot be interacted with. It is
+still possible to send them to the console or remove them from the list using right-click.
+
+<img src="screenshots/observe_variables.png"/>
+
+The last section of the details window is filled with the component's lifecycle hooks. Using right click on
+them allows to place breakpoints inside the hook (either on its instance or class, hooks like mounted and
+willStart cannot have instance-based breakpoints because they will never trigger). Conditions in conditional
+breakpoints will be evaluated in the context of the component's definition.
+
+<img src="screenshots/hooks.png"/>
+
+There are several icons available to perform several of the actions described before in the components
+tree context menu and all these actions are also available by opening the menu by right-clicking on the
+component's name. Using the left click on the component's name will focus it in the components tree.
+
+It is also possible to edit any of the leaf node properties. To do so, you must double click on the
+property's value and modify it using the freshly created input then press enter to apply the changes.
+Do note that the modified values should be written in JSON format in order to be valid (examples:
+89, "yes", undefined, null, \["hello", 15\], {"a": 1}, true, ...). Editing any value will produce a
+manual render of the component (or the root component of the application in the case of env values).
+Whether the edition has an impact on the component or not and whether it produces an error is the
+responsability of the user.
+
+<img src="screenshots/edit.png"/>
+
+## Profiler
+
+The profiler tab is the other tab of the owl devtools. It consists in an actions bar at the top and
+a tree/list of events related to the owl components' renders. Here is an example of the events launched
+when entering the Odoo Crm app.
+
+<img src="screenshots/profiler.png"/>
+
+In the initial state, no event is displayed. You need to activate the recording of events before they
+are intercepted by the devtools using the record button.
+
+<img src="screenshots/record.png"/>
+
+The second button is used to clear all the events that have been recorded. The select can be used to
+switch between the tree view (which shows the causality between renders) and the events log view which
+simply displays the events in the exact order they were triggered. In this view, you can expand the create,
+update and destroy events which reveals the component that initiated the event. Also, a transition line will
+appear each time a new animation frame has been loaded between events.
+
+<img src="screenshots/events_log.png"/>
+
+The third button is only visible in tree view and allows to fold all the render events that were recorded.
+Some actions are also available when using the right-click on any event of the tree view for navigation
+purpose in a similar fashion as in the components tree.
+
+<img src="screenshots/tree_actions.png"/>
+
+There is also the Trace Renderings and Trace Subscriptions features. These features are independant of the
+recording of events and have no effect on the profiler tab. The Trace Renderings option is used to log in
+the console all the render events and allows to show their traceback information. Similarly, the Trace
+Subscriptions option logs all the properties that caused a render event and also allows to see the traceback
+of the modification.
+
+<img src="screenshots/trace_rendering.png"/>
+<img src="screenshots/trace_subscriptions.png"/>
+
+The Owl Devtools also allow to inspect iframes coded in Owl: when an Owl iframe is detected in the page,
+the iframe selector will appear next to the tabs. This allows to switch from an iframe to another easily.
+Be aware that switching iframes will clear all record events from the profiler tab. Iframes detection is
+currently not working in the firefox version, we are aware of this issue and will try to address it in the
+future.
+
+<img src="screenshots/iframes.png"/>
+
+## Options
+
+The owl devtools extension has a dark mode feature which defaults to your general devtools settings and can
+be toggled using the sun/moon icon at the top-right corner of the tab. There is also a refresh button to
+completely reset the owl devtools.
+
+<img src="screenshots/darkmode.png"/>
+
+## Troubleshooting
+
+If the feedback from the page to the devtools seems to be cut, you can first try to use the refresh
+button mentioned above but if it still doesn't seem to work, just close the devtools and refresh the page.
+This will eventually happen any time a tab stays opened for too long without being refreshed.

docs/assets/highlight.tomorrow.css

@@ -0,0 +1,72 @@
+/* http://jmblog.github.com/color-themes-for-google-code-highlightjs */
+
+/* Tomorrow Comment */
+.hljs-comment,
+.hljs-quote {
+  color: #8e908c;
+}
+
+/* Tomorrow Red */
+.hljs-variable,
+.hljs-template-variable,
+.hljs-tag,
+.hljs-name,
+.hljs-selector-id,
+.hljs-selector-class,
+.hljs-regexp,
+.hljs-deletion {
+  color: #c82829;
+}
+
+/* Tomorrow Orange */
+.hljs-number,
+.hljs-built_in,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params,
+.hljs-meta,
+.hljs-link {
+  color: #f5871f;
+}
+
+/* Tomorrow Yellow */
+.hljs-attribute {
+  color: #eab700;
+}
+
+/* Tomorrow Green */
+.hljs-string,
+.hljs-symbol,
+.hljs-bullet,
+.hljs-addition {
+  color: #718c00;
+}
+
+/* Tomorrow Blue */
+.hljs-title,
+.hljs-section {
+  color: #4271ae;
+}
+
+/* Tomorrow Purple */
+.hljs-keyword,
+.hljs-selector-tag {
+  color: #8959a8;
+}
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  background: white;
+  color: #4d4d4c;
+  padding: 0.5em;
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: bold;
+}

docs/assets/main.css

@@ -0,0 +1,116 @@
+html, body {
+  background-color: #fefefe;
+  font-family: Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
+  height: 100%;
+  margin: 0;
+  text-rendering: optimizeLegibility;
+}
+
+body {
+  display: grid;
+  grid-gap: 3rem;
+  grid-template-areas: "header" "nav" "main" "footer";
+  grid-template-columns: 1fr;
+  height: 100%;
+  grid-template-rows: 1fr 3rem 1fr 3rem;
+}
+
+@media screen and (max-width: 800px) {
+  body {
+    grid-template-rows: 1fr 3rem 1fr 5rem;
+  }
+}
+
+a {
+  color: #00A09D;
+  text-decoration: none;
+}
+
+a:hover, a:active, a:visited {
+  text-decoration: underline;
+}
+
+header {
+  grid-area: header;
+  display: flex;
+  align-items: center;
+  flex-direction: column;
+  justify-content: flex-end;
+  text-align: center;
+  padding-top: 3rem !important;
+}
+
+hgroup > p {
+  margin-bottom: auto;
+}
+
+nav {
+  grid-area: nav;
+}
+
+main {
+  grid-area: main;
+  /*justify-self: center;*/
+  grid-column: 1 / -1;
+  /*max-width: 80rem !important;*/
+  /*margin: 3rem 0;*/
+}
+
+footer {
+  grid-area: footer;
+  padding-bottom: 3rem !important;
+}
+
+header, nav, footer {
+  text-align: center;
+}
+
+article {
+  padding: 3rem 0;
+}
+
+article h3 {
+  font-size: 2rem;
+  font-weight: 700;
+}
+
+article.brand {
+  align-items: center;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  text-align: center;
+}
+
+article.design {
+  background-color: #875A7B;
+  color: #f0eeee;
+}
+
+header .homepage-logo {
+  margin-bottom: 2rem;
+}
+
+@media (min-width: 40rem) {
+  .row {
+    flex-direction: column;
+    margin-left: initial;
+    width: 100%;
+  }
+
+  .row .column {
+    margin-bottom: initial;
+    padding: initial;
+  }
+}
+@media (min-width: 60rem) {
+  .row {
+    flex-direction: row;
+    margin-left: -1.0rem;
+    width: calc(100% + 2.0rem);
+  }
+  .row .column {
+    margin-bottom: inherit;
+    padding: 0 1.0rem;
+  }
+}

docs/assets/milligram.css

@@ -0,0 +1,602 @@
+/*!
+ * Milligram v1.3.0
+ * https://milligram.github.io
+ *
+ * Copyright (c) 2017 CJ Patoilo
+ * Licensed under the MIT license
+ */
+
+*,
+*:after,
+*:before {
+  box-sizing: inherit;
+}
+
+html {
+  box-sizing: border-box;
+  font-size: 62.5%;
+}
+
+body {
+  color: #606c76;
+  font-family: 'Roboto', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif;
+  font-size: 1.6em;
+  font-weight: 300;
+  letter-spacing: .01em;
+  line-height: 1.6;
+}
+
+blockquote {
+  border-left: 0.3rem solid #d1d1d1;
+  margin-left: 0;
+  margin-right: 0;
+  padding: 1rem 1.5rem;
+}
+
+blockquote *:last-child {
+  margin-bottom: 0;
+}
+
+.button,
+button,
+input[type='button'],
+input[type='reset'],
+input[type='submit'] {
+  background-color: #9b4dca;
+  border: 0.1rem solid #9b4dca;
+  border-radius: .4rem;
+  color: #fff;
+  cursor: pointer;
+  display: inline-block;
+  font-size: 1.1rem;
+  font-weight: 700;
+  height: 3.8rem;
+  letter-spacing: .1rem;
+  line-height: 3.8rem;
+  padding: 0 3.0rem;
+  text-align: center;
+  text-decoration: none;
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.button:focus, .button:hover,
+button:focus,
+button:hover,
+input[type='button']:focus,
+input[type='button']:hover,
+input[type='reset']:focus,
+input[type='reset']:hover,
+input[type='submit']:focus,
+input[type='submit']:hover {
+  background-color: #606c76;
+  border-color: #606c76;
+  color: #fff;
+  outline: 0;
+}
+
+.button[disabled],
+button[disabled],
+input[type='button'][disabled],
+input[type='reset'][disabled],
+input[type='submit'][disabled] {
+  cursor: default;
+  opacity: .5;
+}
+
+.button[disabled]:focus, .button[disabled]:hover,
+button[disabled]:focus,
+button[disabled]:hover,
+input[type='button'][disabled]:focus,
+input[type='button'][disabled]:hover,
+input[type='reset'][disabled]:focus,
+input[type='reset'][disabled]:hover,
+input[type='submit'][disabled]:focus,
+input[type='submit'][disabled]:hover {
+  background-color: #9b4dca;
+  border-color: #9b4dca;
+}
+
+.button.button-outline,
+button.button-outline,
+input[type='button'].button-outline,
+input[type='reset'].button-outline,
+input[type='submit'].button-outline {
+  background-color: transparent;
+  color: #9b4dca;
+}
+
+.button.button-outline:focus, .button.button-outline:hover,
+button.button-outline:focus,
+button.button-outline:hover,
+input[type='button'].button-outline:focus,
+input[type='button'].button-outline:hover,
+input[type='reset'].button-outline:focus,
+input[type='reset'].button-outline:hover,
+input[type='submit'].button-outline:focus,
+input[type='submit'].button-outline:hover {
+  background-color: transparent;
+  border-color: #606c76;
+  color: #606c76;
+}
+
+.button.button-outline[disabled]:focus, .button.button-outline[disabled]:hover,
+button.button-outline[disabled]:focus,
+button.button-outline[disabled]:hover,
+input[type='button'].button-outline[disabled]:focus,
+input[type='button'].button-outline[disabled]:hover,
+input[type='reset'].button-outline[disabled]:focus,
+input[type='reset'].button-outline[disabled]:hover,
+input[type='submit'].button-outline[disabled]:focus,
+input[type='submit'].button-outline[disabled]:hover {
+  border-color: inherit;
+  color: #9b4dca;
+}
+
+.button.button-clear,
+button.button-clear,
+input[type='button'].button-clear,
+input[type='reset'].button-clear,
+input[type='submit'].button-clear {
+  background-color: transparent;
+  border-color: transparent;
+  color: #9b4dca;
+}
+
+.button.button-clear:focus, .button.button-clear:hover,
+button.button-clear:focus,
+button.button-clear:hover,
+input[type='button'].button-clear:focus,
+input[type='button'].button-clear:hover,
+input[type='reset'].button-clear:focus,
+input[type='reset'].button-clear:hover,
+input[type='submit'].button-clear:focus,
+input[type='submit'].button-clear:hover {
+  background-color: transparent;
+  border-color: transparent;
+  color: #606c76;
+}
+
+.button.button-clear[disabled]:focus, .button.button-clear[disabled]:hover,
+button.button-clear[disabled]:focus,
+button.button-clear[disabled]:hover,
+input[type='button'].button-clear[disabled]:focus,
+input[type='button'].button-clear[disabled]:hover,
+input[type='reset'].button-clear[disabled]:focus,
+input[type='reset'].button-clear[disabled]:hover,
+input[type='submit'].button-clear[disabled]:focus,
+input[type='submit'].button-clear[disabled]:hover {
+  color: #9b4dca;
+}
+
+code {
+  background: #f4f5f6;
+  border-radius: .4rem;
+  font-size: 86%;
+  margin: 0 .2rem;
+  padding: .2rem .5rem;
+  white-space: nowrap;
+}
+
+pre {
+  background: #f4f5f6;
+  border-left: 0.3rem solid #9b4dca;
+  overflow-y: hidden;
+}
+
+pre > code {
+  border-radius: 0;
+  display: block;
+  padding: 1rem 1.5rem;
+  white-space: pre;
+}
+
+hr {
+  border: 0;
+  border-top: 0.1rem solid #f4f5f6;
+  margin: 3.0rem 0;
+}
+
+input[type='email'],
+input[type='number'],
+input[type='password'],
+input[type='search'],
+input[type='tel'],
+input[type='text'],
+input[type='url'],
+textarea,
+select {
+  -webkit-appearance: none;
+     -moz-appearance: none;
+          appearance: none;
+  background-color: transparent;
+  border: 0.1rem solid #d1d1d1;
+  border-radius: .4rem;
+  box-shadow: none;
+  box-sizing: inherit;
+  height: 3.8rem;
+  padding: .6rem 1.0rem;
+  width: 100%;
+}
+
+input[type='email']:focus,
+input[type='number']:focus,
+input[type='password']:focus,
+input[type='search']:focus,
+input[type='tel']:focus,
+input[type='text']:focus,
+input[type='url']:focus,
+textarea:focus,
+select:focus {
+  border-color: #9b4dca;
+  outline: 0;
+}
+
+select {
+  background: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" height="14" viewBox="0 0 29 14" width="29"><path fill="#d1d1d1" d="M9.37727 3.625l5.08154 6.93523L19.54036 3.625"/></svg>') center right no-repeat;
+  padding-right: 3.0rem;
+}
+
+select:focus {
+  background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" height="14" viewBox="0 0 29 14" width="29"><path fill="#9b4dca" d="M9.37727 3.625l5.08154 6.93523L19.54036 3.625"/></svg>');
+}
+
+textarea {
+  min-height: 6.5rem;
+}
+
+label,
+legend {
+  display: block;
+  font-size: 1.6rem;
+  font-weight: 700;
+  margin-bottom: .5rem;
+}
+
+fieldset {
+  border-width: 0;
+  padding: 0;
+}
+
+input[type='checkbox'],
+input[type='radio'] {
+  display: inline;
+}
+
+.label-inline {
+  display: inline-block;
+  font-weight: normal;
+  margin-left: .5rem;
+}
+
+.container {
+  margin: 0 auto;
+  max-width: 112.0rem;
+  padding: 0 2.0rem;
+  position: relative;
+  width: 100%;
+}
+
+.row {
+  display: flex;
+  flex-direction: column;
+  padding: 0;
+  width: 100%;
+}
+
+.row.row-no-padding {
+  padding: 0;
+}
+
+.row.row-no-padding > .column {
+  padding: 0;
+}
+
+.row.row-wrap {
+  flex-wrap: wrap;
+}
+
+.row.row-top {
+  align-items: flex-start;
+}
+
+.row.row-bottom {
+  align-items: flex-end;
+}
+
+.row.row-center {
+  align-items: center;
+}
+
+.row.row-stretch {
+  align-items: stretch;
+}
+
+.row.row-baseline {
+  align-items: baseline;
+}
+
+.row .column {
+  display: block;
+  flex: 1 1 auto;
+  margin-left: 0;
+  max-width: 100%;
+  width: 100%;
+}
+
+.row .column.column-offset-10 {
+  margin-left: 10%;
+}
+
+.row .column.column-offset-20 {
+  margin-left: 20%;
+}
+
+.row .column.column-offset-25 {
+  margin-left: 25%;
+}
+
+.row .column.column-offset-33, .row .column.column-offset-34 {
+  margin-left: 33.3333%;
+}
+
+.row .column.column-offset-50 {
+  margin-left: 50%;
+}
+
+.row .column.column-offset-66, .row .column.column-offset-67 {
+  margin-left: 66.6666%;
+}
+
+.row .column.column-offset-75 {
+  margin-left: 75%;
+}
+
+.row .column.column-offset-80 {
+  margin-left: 80%;
+}
+
+.row .column.column-offset-90 {
+  margin-left: 90%;
+}
+
+.row .column.column-10 {
+  flex: 0 0 10%;
+  max-width: 10%;
+}
+
+.row .column.column-20 {
+  flex: 0 0 20%;
+  max-width: 20%;
+}
+
+.row .column.column-25 {
+  flex: 0 0 25%;
+  max-width: 25%;
+}
+
+.row .column.column-33, .row .column.column-34 {
+  flex: 0 0 33.3333%;
+  max-width: 33.3333%;
+}
+
+.row .column.column-40 {
+  flex: 0 0 40%;
+  max-width: 40%;
+}
+
+.row .column.column-50 {
+  flex: 0 0 50%;
+  max-width: 50%;
+}
+
+.row .column.column-60 {
+  flex: 0 0 60%;
+  max-width: 60%;
+}
+
+.row .column.column-66, .row .column.column-67 {
+  flex: 0 0 66.6666%;
+  max-width: 66.6666%;
+}
+
+.row .column.column-75 {
+  flex: 0 0 75%;
+  max-width: 75%;
+}
+
+.row .column.column-80 {
+  flex: 0 0 80%;
+  max-width: 80%;
+}
+
+.row .column.column-90 {
+  flex: 0 0 90%;
+  max-width: 90%;
+}
+
+.row .column .column-top {
+  align-self: flex-start;
+}
+
+.row .column .column-bottom {
+  align-self: flex-end;
+}
+
+.row .column .column-center {
+  -ms-grid-row-align: center;
+      align-self: center;
+}
+
+@media (min-width: 40rem) {
+  .row {
+    flex-direction: row;
+    margin-left: -1.0rem;
+    width: calc(100% + 2.0rem);
+  }
+  .row .column {
+    margin-bottom: inherit;
+    padding: 0 1.0rem;
+  }
+}
+
+a {
+  color: #9b4dca;
+  text-decoration: none;
+}
+
+a:focus, a:hover {
+  color: #606c76;
+}
+
+dl,
+ol,
+ul {
+  list-style: none;
+  margin-top: 0;
+  padding-left: 0;
+}
+
+dl dl,
+dl ol,
+dl ul,
+ol dl,
+ol ol,
+ol ul,
+ul dl,
+ul ol,
+ul ul {
+  font-size: 90%;
+  margin: 1.5rem 0 1.5rem 3.0rem;
+}
+
+ol {
+  list-style: decimal inside;
+}
+
+ul {
+  list-style: circle inside;
+}
+
+.button,
+button,
+dd,
+dt,
+li {
+  margin-bottom: 1.0rem;
+}
+
+fieldset,
+input,
+select,
+textarea {
+  margin-bottom: 1.5rem;
+}
+
+blockquote,
+dl,
+figure,
+form,
+ol,
+p,
+pre,
+table,
+ul {
+  margin-bottom: 2.5rem;
+}
+
+table {
+  border-spacing: 0;
+  width: 100%;
+}
+
+td,
+th {
+  border-bottom: 0.1rem solid #e1e1e1;
+  padding: 1.2rem 1.5rem;
+  text-align: left;
+}
+
+td:first-child,
+th:first-child {
+  padding-left: 0;
+}
+
+td:last-child,
+th:last-child {
+  padding-right: 0;
+}
+
+b,
+strong {
+  font-weight: bold;
+}
+
+p {
+  margin-top: 0;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-weight: 300;
+  letter-spacing: -.1rem;
+  margin-bottom: 2.0rem;
+  margin-top: 0;
+}
+
+h1 {
+  font-size: 4.6rem;
+  line-height: 1.2;
+}
+
+h2 {
+  font-size: 3.6rem;
+  line-height: 1.25;
+}
+
+h3 {
+  font-size: 2.8rem;
+  line-height: 1.3;
+}
+
+h4 {
+  font-size: 2.2rem;
+  letter-spacing: -.08rem;
+  line-height: 1.35;
+}
+
+h5 {
+  font-size: 1.8rem;
+  letter-spacing: -.05rem;
+  line-height: 1.5;
+}
+
+h6 {
+  font-size: 1.6rem;
+  letter-spacing: 0;
+  line-height: 1.4;
+}
+
+img {
+  max-width: 100%;
+}
+
+.clearfix:after {
+  clear: both;
+  content: ' ';
+  display: table;
+}
+
+.float-left {
+  float: left;
+}
+
+.float-right {
+  float: right;
+}
+
+/*# sourceMappingURL=milligram.css.map */

docs/assets/normalize.css

@@ -0,0 +1,349 @@
+/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */
+
+/* Document
+   ========================================================================== */
+
+/**
+ * 1. Correct the line height in all browsers.
+ * 2. Prevent adjustments of font size after orientation changes in iOS.
+ */
+
+html {
+  line-height: 1.15; /* 1 */
+  -webkit-text-size-adjust: 100%; /* 2 */
+}
+
+/* Sections
+   ========================================================================== */
+
+/**
+ * Remove the margin in all browsers.
+ */
+
+body {
+  margin: 0;
+}
+
+/**
+ * Render the `main` element consistently in IE.
+ */
+
+main {
+  display: block;
+}
+
+/**
+ * Correct the font size and margin on `h1` elements within `section` and
+ * `article` contexts in Chrome, Firefox, and Safari.
+ */
+
+h1 {
+  font-size: 2em;
+  margin: 0.67em 0;
+}
+
+/* Grouping content
+   ========================================================================== */
+
+/**
+ * 1. Add the correct box sizing in Firefox.
+ * 2. Show the overflow in Edge and IE.
+ */
+
+hr {
+  box-sizing: content-box; /* 1 */
+  height: 0; /* 1 */
+  overflow: visible; /* 2 */
+}
+
+/**
+ * 1. Correct the inheritance and scaling of font size in all browsers.
+ * 2. Correct the odd `em` font sizing in all browsers.
+ */
+
+pre {
+  font-family: monospace, monospace; /* 1 */
+  font-size: 1em; /* 2 */
+}
+
+/* Text-level semantics
+   ========================================================================== */
+
+/**
+ * Remove the gray background on active links in IE 10.
+ */
+
+a {
+  background-color: transparent;
+}
+
+/**
+ * 1. Remove the bottom border in Chrome 57-
+ * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.
+ */
+
+abbr[title] {
+  border-bottom: none; /* 1 */
+  text-decoration: underline; /* 2 */
+  text-decoration: underline dotted; /* 2 */
+}
+
+/**
+ * Add the correct font weight in Chrome, Edge, and Safari.
+ */
+
+b,
+strong {
+  font-weight: bolder;
+}
+
+/**
+ * 1. Correct the inheritance and scaling of font size in all browsers.
+ * 2. Correct the odd `em` font sizing in all browsers.
+ */
+
+code,
+kbd,
+samp {
+  font-family: monospace, monospace; /* 1 */
+  font-size: 1em; /* 2 */
+}
+
+/**
+ * Add the correct font size in all browsers.
+ */
+
+small {
+  font-size: 80%;
+}
+
+/**
+ * Prevent `sub` and `sup` elements from affecting the line height in
+ * all browsers.
+ */
+
+sub,
+sup {
+  font-size: 75%;
+  line-height: 0;
+  position: relative;
+  vertical-align: baseline;
+}
+
+sub {
+  bottom: -0.25em;
+}
+
+sup {
+  top: -0.5em;
+}
+
+/* Embedded content
+   ========================================================================== */
+
+/**
+ * Remove the border on images inside links in IE 10.
+ */
+
+img {
+  border-style: none;
+}
+
+/* Forms
+   ========================================================================== */
+
+/**
+ * 1. Change the font styles in all browsers.
+ * 2. Remove the margin in Firefox and Safari.
+ */
+
+button,
+input,
+optgroup,
+select,
+textarea {
+  font-family: inherit; /* 1 */
+  font-size: 100%; /* 1 */
+  line-height: 1.15; /* 1 */
+  margin: 0; /* 2 */
+}
+
+/**
+ * Show the overflow in IE.
+ * 1. Show the overflow in Edge.
+ */
+
+button,
+input { /* 1 */
+  overflow: visible;
+}
+
+/**
+ * Remove the inheritance of text transform in Edge, Firefox, and IE.
+ * 1. Remove the inheritance of text transform in Firefox.
+ */
+
+button,
+select { /* 1 */
+  text-transform: none;
+}
+
+/**
+ * Correct the inability to style clickable types in iOS and Safari.
+ */
+
+button,
+[type="button"],
+[type="reset"],
+[type="submit"] {
+  -webkit-appearance: button;
+}
+
+/**
+ * Remove the inner border and padding in Firefox.
+ */
+
+button::-moz-focus-inner,
+[type="button"]::-moz-focus-inner,
+[type="reset"]::-moz-focus-inner,
+[type="submit"]::-moz-focus-inner {
+  border-style: none;
+  padding: 0;
+}
+
+/**
+ * Restore the focus styles unset by the previous rule.
+ */
+
+button:-moz-focusring,
+[type="button"]:-moz-focusring,
+[type="reset"]:-moz-focusring,
+[type="submit"]:-moz-focusring {
+  outline: 1px dotted ButtonText;
+}
+
+/**
+ * Correct the padding in Firefox.
+ */
+
+fieldset {
+  padding: 0.35em 0.75em 0.625em;
+}
+
+/**
+ * 1. Correct the text wrapping in Edge and IE.
+ * 2. Correct the color inheritance from `fieldset` elements in IE.
+ * 3. Remove the padding so developers are not caught out when they zero out
+ *    `fieldset` elements in all browsers.
+ */
+
+legend {
+  box-sizing: border-box; /* 1 */
+  color: inherit; /* 2 */
+  display: table; /* 1 */
+  max-width: 100%; /* 1 */
+  padding: 0; /* 3 */
+  white-space: normal; /* 1 */
+}
+
+/**
+ * Add the correct vertical alignment in Chrome, Firefox, and Opera.
+ */
+
+progress {
+  vertical-align: baseline;
+}
+
+/**
+ * Remove the default vertical scrollbar in IE 10+.
+ */
+
+textarea {
+  overflow: auto;
+}
+
+/**
+ * 1. Add the correct box sizing in IE 10.
+ * 2. Remove the padding in IE 10.
+ */
+
+[type="checkbox"],
+[type="radio"] {
+  box-sizing: border-box; /* 1 */
+  padding: 0; /* 2 */
+}
+
+/**
+ * Correct the cursor style of increment and decrement buttons in Chrome.
+ */
+
+[type="number"]::-webkit-inner-spin-button,
+[type="number"]::-webkit-outer-spin-button {
+  height: auto;
+}
+
+/**
+ * 1. Correct the odd appearance in Chrome and Safari.
+ * 2. Correct the outline style in Safari.
+ */
+
+[type="search"] {
+  -webkit-appearance: textfield; /* 1 */
+  outline-offset: -2px; /* 2 */
+}
+
+/**
+ * Remove the inner padding in Chrome and Safari on macOS.
+ */
+
+[type="search"]::-webkit-search-decoration {
+  -webkit-appearance: none;
+}
+
+/**
+ * 1. Correct the inability to style clickable types in iOS and Safari.
+ * 2. Change font properties to `inherit` in Safari.
+ */
+
+::-webkit-file-upload-button {
+  -webkit-appearance: button; /* 1 */
+  font: inherit; /* 2 */
+}
+
+/* Interactive
+   ========================================================================== */
+
+/*
+ * Add the correct display in Edge, IE 10+, and Firefox.
+ */
+
+details {
+  display: block;
+}
+
+/*
+ * Add the correct display in all browsers.
+ */
+
+summary {
+  display: list-item;
+}
+
+/* Misc
+   ========================================================================== */
+
+/**
+ * Add the correct display in IE 10+.
+ */
+
+template {
+  display: none;
+}
+
+/**
+ * Add the correct display in IE 10.
+ */
+
+[hidden] {
+  display: none;
+}

docs/counter.js

@@ -0,0 +1,15 @@
+import { mount, Component, useState, loadFile } from "@odoo/owl";
+
+class Counter extends Component {
+  static template = "Counter";
+  setup() {
+    this.state = useState({ value: 0 });
+  }
+
+  increment() {
+    this.state.value++;
+  }
+}
+const templates = await loadFile("./counter.xml");
+
+mount(Counter, document.getElementById("app-container"), { templates });

docs/counter.xml

@@ -0,0 +1,7 @@
+<templates>
+  <t t-name="Counter">
+    <button t-on-click="increment">
+      Click Me! [<t t-esc="state.value"/>]
+    </button>
+  </t>
+</templates>

docs/display_code.js

@@ -0,0 +1,9 @@
+import { loadFile } from "@odoo/owl";
+
+for (const [className, type] of [["xml", "xml"], ["javascript", "js"]]) {
+    loadFile(`./counter.${type}`).then(code => {
+        const el = document.querySelector(`code.${className}`);
+        el.textContent = code;
+        hljs.highlightBlock(el);
+    })
+}

docs/index.html

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>OWL Framework</title>
+  <link rel="icon" href="data:,">
+  <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Roboto:300,300italic,700,700italic">
+  <link rel="stylesheet" href="assets/normalize.css">
+  <link rel="stylesheet" href="assets/milligram.css">
+  <link rel="stylesheet" href="assets/highlight.tomorrow.css">
+  <link rel="stylesheet" href="assets/main.css">
+  <script type="importmap">{ "imports": { "@odoo/owl": "./owl.js" } }</script>
+</head>
+<body>
+  <header class="container">
+    <img class="homepage-logo" src="assets/owl_1f989.png" alt="OWL Logo">
+    <hgroup>
+      <h1>OWL Framework</h1>
+      <p>Mysterious OWL: A web framework for structured, dynamic and maintainable applications</p>
+    </hgroup>
+  </header>
+  <nav class="container">
+    <p>
+      <a href="https://github.com/odoo/owl" title="https://github.com/odoo/owl">Github</a>
+      &bull;
+      <a href="https://github.com/odoo/owl/blob/master/doc/readme.md">Documentation</a>
+      &bull;
+      <a href="playground/">Playground</a>
+    </p>
+  </nav>
+  <main>
+    <article class="design">
+      <div class="container">
+        <h2>Why OWL?</h2>
+        <div class="row">
+          <section class="column">
+            <h3>XML based</h3>
+            <p>Templates are based on the XML format, which allows interesting applications. For example, they could be stored in a database and modified dynamically with <tt>xpaths</tt>.</p>
+          </section>
+          <section class="column">
+            <h3>Templates compiled in the browser</h3>
+            <p>This may not be a good fit for all applications, but if you need to generate dynamically user interfaces in the browser, this is very powerful. For example, a generic form view component could generate a specific form user interface for each various models, from a XML view.</p>
+          </section>
+          <section class="column">
+            <h3>No toolchain required</h3>
+            <p>This is extremely useful for some applications, if, for various reasons (security/deployment/dynamic modules/specific assets tools), it is not ok to use standard web tools based on <tt>npm</tt>.</p>
+          </section>
+        </div>
+      </div>
+    </article>
+    <article class="example">
+      <div class="container">
+        <h2>Example</h2>
+        <div class="row">
+          <section class="column">
+            <pre><code class="javascript"></code></pre>
+          </section>
+          <section class="column">
+            <pre><code class="xml"></code></pre>
+            <div id="app-container"></div>
+          </section>
+        </div>
+      </div>
+    </article>
+  </main>
+  <footer>
+    <p><a href=".">OWL</a> is licensed under LGPLv3.<br>Logo from <a href="https://github.com/googlefonts/noto-emoji">Google Noto Emoji Font</a>, licensed under Apache License 2.0</p>
+  </footer>
+  <script src="assets/highlight.pack.js"></script>
+  <script type="module" src="display_code.js"></script>
+  <script type="module" src="counter.js"></script>
+</body>
+</html>

docs/playground/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>OWL Playground</title>
+    <link rel="icon" href="data:,">
+
+    <script src="libs/ace.js" type="text/javascript" charset="utf-8"></script>
+    <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.1/css/solid.css" integrity="sha384-QokYePQSOwpBDuhlHOsX0ymF6R/vLk/UQVz3WHa6wygxI5oGTmDTv8wahFOSspdm" crossorigin="anonymous">
+    <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.1/css/fontawesome.css" integrity="sha384-vd1e11sR28tEK9YANUtpIOdjGW14pS87bUBuOIoBILVWLFnS+MCX9T6MMf0VdPGq" crossorigin="anonymous">
+    
+    <!-- Application JS/CSS -->
+    <link rel="stylesheet" href="playground.css">
+    <script type="module" src="playground.js"></script>
+  </head>
+  <body>
+  </body>
+</html>

docs/playground/playground.css

@@ -20,7 +20,7 @@ body {
   display: grid;
   height: 100%;
   width: 100%;
-  grid-template-columns: auto 8px 100%;
+  grid-template-columns: auto 8px 1fr;
 }
 
 /* LEFT BAR ****************************************/
@@ -79,6 +79,19 @@ body {
   margin: 5px;
 }
 
+.share-code {
+  position: relative;
+}
+
+.copied-notification {
+  font-size: x-small;
+  position: absolute;
+  bottom: -5px;
+  white-space: nowrap;
+  left: 50%;
+  transform: translateX(-50%);
+}
+
 /* TABBED EDITOR ****************************************/
 
 .tabbed-editor {

docs/playground/playground.js

@@ -1,7 +1,19 @@
-import { SAMPLES } from "./samples.js";
 import { debounce, loadJS } from "./utils.js";
-import { exportStandaloneApp } from "./export_snippet.js";
-const { useState, useRef, onMounted, onWillUnmount, onPatched, onWillUpdateProps } = owl;
+import {
+  App,
+  Component,
+  useState,
+  useRef,
+  onMounted,
+  onWillUnmount,
+  onPatched,
+  onWillUpdateProps,
+  loadFile as _loadFile,
+  whenReady,
+  __info__,
+  useEffect,
+  onWillStart,
+} from "../owl.js";
 
 //------------------------------------------------------------------------------
 // Constants, helpers, utils
@@ -16,40 +28,37 @@ const MODES = {
 const DEFAULT_XML = `<templates>
 </templates>`;
 
+// Memoize loadFile so that samples aren't reloaded whenever a sample is selected
+const fileCache = {};
+const loadFile = (path) => {
+  if (!(path in fileCache)) {
+    fileCache[path] = _loadFile(path);
+  }
+  return fileCache[path];
+}
+
 /**
  * Make an iframe, with all the js, css and xml properly injected.
  */
 function makeCodeIframe(js, css, xml) {
-  const sanitizedXML = xml.replace(/<!--[\s\S]*?-->/g, "").replace(/`/g, '\\\`');
-
-  // create iframe
   const iframe = document.createElement("iframe");
-
   iframe.onload = () => {
     const doc = iframe.contentDocument;
-    const utilsMod = doc.createElement("script");
-    utilsMod.setAttribute("type", "module");
-    utilsMod.setAttribute("src", "utils.js");
-    doc.head.appendChild(utilsMod);
-    // inject js
-    const owlScript = doc.createElement("script");
-    owlScript.type = "text/javascript";
-    owlScript.src = "../owl.js";
-    owlScript.addEventListener("load", () => {
-      const script = doc.createElement("script");
-      script.type = "module";
-      const content = `
-        (async function(TEMPLATES) {
-          ${js}
-        })(\`${sanitizedXML}\`)`;
-      script.innerHTML = content;
-      doc.body.appendChild(script);
-    });
-    doc.head.appendChild(owlScript);
 
-    // inject css
+    const importMap = doc.createElement("script");
+    importMap.type = "importmap";
+    importMap.textContent = `{ "imports": { "@odoo/owl": "../owl.js" } }`;
+    doc.head.appendChild(importMap);
+
+    const script = doc.createElement("script");
+    script.type = "module";
+    // escape characters with special meaning in template literals
+    const escapedXml = xml.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/, "\\${");
+    script.textContent = `const TEMPLATES = \`${escapedXml}\`\n${js}`;
+    doc.body.appendChild(script);
+
     const style = document.createElement("style");
-    style.innerHTML = css;
+    style.innerText = css;
     doc.head.appendChild(style);
   };
   return iframe;
@@ -58,53 +67,84 @@ function makeCodeIframe(js, css, xml) {
 //------------------------------------------------------------------------------
 // SAMPLES
 //------------------------------------------------------------------------------
+
+const SAMPLES = [
+  {
+    description: "Components",
+    folder: "components",
+    code: ["js", "xml", "css"],
+  },
+  {
+    description: "Form Input Bindings",
+    folder: "form",
+    code: ["js", "xml"],
+  },
+  {
+    description: "Inline templates",
+    folder: "single_file_component",
+    code: ["js"],
+  },
+  {
+    description: "Lifecycle demo",
+    folder: "lifecycle_demo",
+    code: ["js", "xml", "css"],
+  },
+  {
+    description: "Customized hook",
+    folder: "custom_hooks",
+    code: ["js", "xml", "css"],
+  },
+  {
+    description: "Todo List App (with reactivity)",
+    folder: "todo_app",
+    code: ["js", "xml", "css"],
+  },
+  {
+    description: "Responsive app",
+    folder: "responsive_app",
+    code: ["js", "xml", "css"],
+  },
+  {
+    description: "Slots And Generic Components",
+    folder: "slots",
+    code: ["js", "xml", "css"],
+  },
+  {
+    description: "Window Management System",
+    folder: "window_manager",
+    code: ["js", "xml", "css"],
+  },
+  {
+    description: "Benchmark example",
+    folder: "benchmark",
+    code: ["js", "xml", "css"],
+  },
+]
+
 function loadSamples() {
-  let result = SAMPLES.slice();
+  const result = SAMPLES.map(({ description, folder, code }) => ({
+    description,
+    code: async () => Object.fromEntries(
+      await Promise.all(
+        code.map(async (type) => [type, await loadFile(`./samples/${folder}/${folder}.${type}`)])
+      )
+    ),
+  }));
   const localSample = localStorage.getItem("owl-playground-local-sample");
   if (localSample) {
     const { js, css, xml } = JSON.parse(localSample);
     result.unshift({
       description: "Local Storage Code",
-      code: js,
-      xml,
-      css
+      code: () => Promise.resolve({ js, xml, css }),
     });
   }
   return result;
 }
 
-function saveLocalSample(js, css, xml) {
-  const str = JSON.stringify({ js, css, xml });
-  localStorage.setItem("owl-playground-local-sample", str);
-}
-
-function deleteLocalSample() {
-  localStorage.removeItem("owl-playground-local-sample");
-}
-
-function useSamples() {
-  const samples = loadSamples();
-  const component = owl.useComponent();
-  let interval;
-
-  onMounted(() => {
-    const state = component.state;
-    interval = setInterval(() => {
-      if (component.isDirty) {
-        saveLocalSample(state.js, state.css, state.xml);
-      }
-    }, 1000);
-  });
-  onWillUnmount(() => {
-    clearInterval(interval);
-  });
-  return samples;
-}
-
 //------------------------------------------------------------------------------
 // Tabbed editor
 //------------------------------------------------------------------------------
-class TabbedEditor extends owl.Component {
+class TabbedEditor extends Component {
   setup() {
     const props = this.props;
     this.state = useState({
@@ -168,7 +208,7 @@ class TabbedEditor extends owl.Component {
       const resizer = ev => {
         const delta = ev.clientY - y;
         y = ev.clientY;
-        this.trigger("updatePanelHeight", { delta });
+        this.props.updatePanelHeight({ delta });
       };
       document.body.addEventListener("mousemove", resizer);
       document.body.addEventListener("mouseup", () => {
@@ -205,25 +245,51 @@ TabbedEditor.template = "TabbedEditor";
 //------------------------------------------------------------------------------
 // MAIN APP
 //------------------------------------------------------------------------------
-class App extends owl.Component {
+class Playground extends Component {
+  static template = "Playground";
+  static components = { TabbedEditor };
   setup() {
-    this.version = owl.__info__.version;
-    this.SAMPLES = useSamples();
-    this.isDirty = false;
+    this.version = __info__.version;
 
+    this.isDirty = false;
     this.state = useState({
-      js: this.SAMPLES[0].code,
-      css: this.SAMPLES[0].css || "",
-      xml: this.SAMPLES[0].xml || DEFAULT_XML,
+      js: "",
+      css: "",
+      xml: DEFAULT_XML,
       displayWelcome: true,
       splitLayout: true,
       leftPaneWidth: Math.ceil(window.innerWidth / 2),
       topPanelHeight: null
     });
 
+    this.samples = loadSamples();
+    if (window.location.hash) {
+      try {
+        const { js, css, xml } = JSON.parse(atob(decodeURIComponent(window.location.hash.slice(1))));
+        if ([js, css, xml].every(item => typeof item === "string")) {
+          Object.assign(this.state, { js, css, xml });
+        }
+      } catch {}
+    }
+    onWillStart(async () => {
+      if (!this.state.js) {
+        this.setSample(await this.samples[0].code());
+      }
+    })
+    useEffect(() => {
+      const interval = setInterval(() => {
+        if (this.isDirty) {
+          const { js, css, xml } = this.state;
+          const str = JSON.stringify({ js, css, xml });
+          localStorage.setItem("owl-playground-local-sample", str);
+        }
+      }, 1000);
+      return () => clearInterval(interval);
+    }, () => []);
+
     this.toggleLayout = debounce(this.toggleLayout, 250, true);
     this.runCode = debounce(this.runCode, 250, true);
-    this.downloadCode = debounce(this.downloadCode, 250, true);
+    this.exportStandaloneApp = debounce(this.exportStandaloneApp, 250, true);
     this.content = useRef("content");
     this.updateCode = this.updateCode.bind(this);
   }
@@ -237,12 +303,23 @@ class App extends owl.Component {
     this.content.el.appendChild(subiframe);
   }
 
-  setSample(ev) {
-    const sample = this.SAMPLES.find(s => s.description === ev.target.value);
-    this.state.js = sample.code;
+  shareCode() {
+    const state = btoa(JSON.stringify({ js: this.state.js, css: this.state.css, xml: this.state.xml }));
+    const link = new URL(window.location.href);
+    link.hash = state;
+    if (navigator.clipboard) {
+      navigator.clipboard.writeText(link.href);
+      clearTimeout(this.state.copied)
+      this.state.copied = setTimeout(() => this.state.copied = null, 2000);
+    }
+    window.location.href = link.href;
+  }
+
+  setSample(sample) {
+    this.state.js = sample.js;
     this.state.css = sample.css || "";
     this.state.xml = sample.xml || DEFAULT_XML;
-    deleteLocalSample();
+    localStorage.removeItem("owl-playground-local-sample");
     this.isDirty = false;
   }
 
@@ -250,14 +327,14 @@ class App extends owl.Component {
     return `width:${this.state.leftPaneWidth}px`;
   }
 
-  get rightPaneStyle() {
-    return `width:${window.innerWidth - 6 - this.state.leftPaneWidth}px`;
-  }
-
   get topEditorStyle() {
     return `flex: 0 0 ${this.state.topPanelHeight}px`;
   }
 
+  async onSampleChange(ev) {
+    this.setSample(await this.samples.find(s => s.description === ev.target.value).code());
+  }
+
   onMouseDown() {
     const resizer = ev => {
       this.state.leftPaneWidth = ev.clientX;
@@ -284,39 +361,40 @@ class App extends owl.Component {
   toggleLayout() {
     this.state.splitLayout = !this.state.splitLayout;
   }
-  updatePanelHeight(ev) {
-    if (!ev.detail.delta) {
-      return;
-    }
-    let height = this.state.topPanelHeight;
-    if (!height) {
-      height = document.getElementsByClassName("tabbed-editor")[0].clientHeight;
-    }
-    this.state.topPanelHeight = height + ev.detail.delta;
+  updatePanelHeight({ delta }) {
+    let height = this.state.topPanelHeight || document.querySelector(".tabbed-editor").clientHeight;
+    this.state.topPanelHeight = height + delta;
   }
 
-  async downloadCode() {
+  async exportStandaloneApp() {
     const { js, css, xml } = this.state;
-    const content = await exportStandaloneApp(js, css, xml);
+
+    await loadJS("libs/jszip.min.js");
+    const zip = new JSZip();
+    zip.file("app.py", await loadFile("./standalone_app/app.py"));
+    zip.file("index.html", await loadFile("./standalone_app/index.html"));
+    zip.file("owl.js", await loadFile("../owl.js"));
+    zip.file("app.js", `const TEMPLATES = await (await fetch('app.xml')).text();\n${js}`);
+    zip.file("app.css", css);
+    zip.file("app.xml", xml);
+
     await loadJS("libs/FileSaver.min.js");
-    saveAs(content, "app.zip");
+    saveAs(await zip.generateAsync({ type: "blob" }), "app.zip");
   }
 }
-App.components = { TabbedEditor };
-App.template = "App";
 
 //------------------------------------------------------------------------------
 // Application initialization
 //------------------------------------------------------------------------------
 async function start() {
-  document.title = `${document.title} (v${owl.__info__.version})`;
-  const commit = `https://github.com/odoo/owl/commit/${owl.__info__.hash}`;
+  document.title = `${document.title} (v${__info__.version})`;
+  const commit = `https://github.com/odoo/owl/commit/${__info__.hash}`;
   console.info(`This application is using Owl built with the following commit:`, commit);
   const [templates] = await Promise.all([
-    owl.loadFile("templates.xml"),
-    owl.whenReady()
+    loadFile("templates.xml"),
+    whenReady()
   ]);
-  const rootApp = new owl.App(App);
+  const rootApp = new App(Playground, { name: "Owl Playground" });
   rootApp.addTemplates(templates);
 
   await  rootApp.mount(document.body);

docs/playground/samples/benchmark/benchmark.css

@@ -0,0 +1,11 @@
+tr.danger {
+  font-weight: bold;
+}
+
+.remove:hover {
+  font-weight: bold;
+}
+.remove {
+  cursor: pointer;
+}
+  

docs/playground/samples/benchmark/benchmark.js

@@ -0,0 +1,124 @@
+import { Component, mount, useState, onPatched} from "@odoo/owl";
+
+// -----------------------------------------------------------------------------
+// Data generation
+// -----------------------------------------------------------------------------
+
+let idCounter = 1;
+const adjectives = [
+    "pretty", "large", "big", "small", "tall", "short", "long", "handsome", "plain",
+    "quaint", "clean", "elegant", "easy", "angry", "crazy", "helpful", "mushy", "odd",
+    "unsightly", "adorable", "important", "inexpensive", "cheap", "expensive", "fancy"];
+const colours = ["red", "yellow", "blue", "green", "pink", "brown", "purple", "brown", "white", "black", "orange"];
+const nouns = ["table", "chair", "house", "bbq", "desk", "car", "pony", "cookie", "sandwich", "burger", "pizza", "mouse", "keyboard"];
+
+function _random (max) { return Math.round(Math.random() * 1000) % max; };
+
+function buildData(count) {
+    const data = new Array(count);
+    for (let i = 0; i < count; i++) {
+        const label = `${adjectives[_random(adjectives.length)]} ${colours[_random(colours.length)]} ${nouns[_random(nouns.length)]}`;
+        data[i] = {
+            id: idCounter++,
+            label,
+        };
+    }
+    return data;
+}
+
+// -----------------------------------------------------------------------------
+// Components
+// -----------------------------------------------------------------------------
+class Button extends Component {
+  static template = "Button";
+}
+
+
+class Row extends Component {
+  static template = "Row";
+}
+
+class Root extends Component {
+  static template = "Root";
+  static components = { Button, Row };
+
+  setup() {
+      this.state = useState({
+          rows: [],
+          selectedRowId: null
+      });
+      this.benchmarking = false;
+      onPatched(() => {
+          if (this.benchmarking) {
+              this.stop();
+          }
+      });
+    }
+    
+    start(descr) {
+        this.benchmarking = `[${descr}]`;
+        console.time(this.benchmarking);
+    }
+    stop() {
+        console.timeEnd(this.benchmarking);
+        this.benchmarking = false;  
+    }
+
+    run() {
+        this.start('add1000');
+        this.state.rows = buildData(1000);
+        this.state.selectedRowId = null;
+    }
+    
+    runLots() {
+        this.start('add10_000');
+        this.state.rows = buildData(10_000);
+        this.state.selectedRowId = null;
+    }
+    
+    add() {
+        this.start('append1000');
+        this.state.rows = this.state.rows.concat(buildData(1000));
+    }
+    
+    update() {
+        this.start('update1/10th');
+        let index = 0;
+        const rows = this.state.rows;
+        while (index < rows.length) {
+            rows[index].label = rows[index].label + " !!!";
+            index += 10;
+        }
+    }
+    
+    clear() {
+        this.start('clear');
+        this.state.rows = [];
+        this.state.selectedRowId = null;
+    }
+    
+    swapRows() {
+        this.start('swap');
+        const rows = this.state.rows;
+        if (rows.length > 998) {
+            let tmp = rows[1];
+            rows[1] = rows[998];
+            rows[998] = tmp;
+        }
+    }
+    
+    selectRow(id) {
+        this.start('select');
+        this.state.selectedRowId = id;
+    }
+    
+    removeRow(id) {
+        this.start('remove1');
+        const rows = this.state.rows;
+        rows.splice(rows.findIndex(row => row.id === id), 1);
+    }
+}
+
+
+// dev=false for benchmarking. we don't want to benchmark dev code!
+mount(Root, document.body, { templates: TEMPLATES, dev: false });

docs/playground/samples/benchmark/benchmark.xml

@@ -0,0 +1,52 @@
+<templates>
+    <t t-name="Button">
+        <div class='col-sm-6 smallpad'>
+            <button t-att-id="props.id" class='btn btn-primary btn-block' type='button' t-on-click="props.onClick">
+                <t t-esc="props.text"/>
+            </button>
+        </div>
+    </t>
+    <t t-name="Row">
+        <tr t-att-class="props.isSelected ? 'danger' : ''">
+            <td class="col-md-1" t-esc="props.row.id" />
+            <td class="col-md-4">
+                <a t-on-click="() => props.onSelect(props.row.id)" t-esc="props.row.label" />
+            </td>
+            <td class="col-md-1">
+                <a t-on-click="() =>  props.onRemove(props.row.id)" class="remove">[x]
+                    <span class='glyphicon glyphicon-remove' aria-hidden="true" />
+                </a>
+            </td>
+            <td class='col-md-6'/>
+        </tr>
+    </t>
+    <t t-name="Root">
+        <div class='container'>
+            <div class='jumbotron'>
+                <div class='row'>
+                    <div class='col-md-6'>
+                        <h1>Owl Keyed</h1>
+                    </div>
+                    <div class='col-md-6'>
+                        <div class='row'>
+                            <Button id="'run'" onClick.bind="run" text="'Create 1,000 rows'" />
+                            <Button id="'runlots'" onClick.bind="runLots" text="'Create 10,000 rows'" />
+                            <Button id="'add'" onClick.bind="add" text="'Append 1,000 rows'" />
+                            <Button id="'update'" onClick.bind="update" text="'Update every 10th row'" />
+                            <Button id="'clear'" onClick.bind="clear" text="'Clear'" />
+                            <Button id="'swaprows'" onClick.bind="swapRows" text="'Swap Rows'" />
+                        </div>
+                    </div>
+                </div>
+            </div>
+            <table class='table table-hover table-striped test-data'>
+                <tbody>
+                    <t t-foreach="state.rows" t-as="row" t-key="row.id">
+                        <Row row="row" isSelected="row.id === state.selectedRowId" onSelect.bind="selectRow" onRemove.bind="removeRow"/>
+                    </t>
+                </tbody>
+            </table>
+            <span class='preloadicon glyphicon glyphicon-remove' aria-hidden="true" />
+        </div>
+    </t>
+</templates>

docs/playground/samples/components/components.css

@@ -0,0 +1,10 @@
+.greeter {
+    font-size: 20px;
+    width: 300px;
+    height: 100px;
+    margin: 5px;
+    text-align: center;
+    line-height: 100px;
+    background-color: #eeeeee;
+    user-select: none;
+}

docs/playground/samples/components/components.js

@@ -0,0 +1,26 @@
+// In this example, we show how components can be defined and created.
+import { Component, useState, mount } from "@odoo/owl";
+
+class Greeter extends Component {
+    static template = "Greeter";
+    
+    setup() {
+        this.state = useState({ word: 'Hello' });
+    }
+
+    toggle() {
+        this.state.word = this.state.word === 'Hi' ? 'Hello' : 'Hi';
+    }
+}
+
+// Main root component
+class Root extends Component {
+    static components = { Greeter };
+    static template = "Root"
+
+    setup() {
+        this.state = useState({ name: 'World'});
+    }
+}
+
+mount(Root, document.body, { templates: TEMPLATES, dev: true });

docs/playground/samples/components/components.xml

@@ -0,0 +1,9 @@
+<templates>
+  <div t-name="Greeter" class="greeter" t-on-click="toggle">
+    <t t-esc="state.word"/>, <t t-esc="props.name"/>
+  </div>
+
+  <t t-name="Root">
+    <Greeter name="state.name"/>
+  </t>
+</templates>

docs/playground/samples/custom_hooks/custom_hooks.css

@@ -0,0 +1,6 @@
+
+button {
+    width: 120px;
+    height: 35px;
+    font-size: 16px;
+}

docs/playground/samples/custom_hooks/custom_hooks.js

@@ -0,0 +1,40 @@
+// In this example, we show how hooks can be used or defined.
+import { Component, mount, useState, onWillDestroy } from "@odoo/owl";
+
+// 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;
+    }
+    window.addEventListener('mousemove', update);
+    onWillDestroy(() => {
+        window.removeEventListener('mousemove', update);
+    });
+
+    return position;
+}
+
+
+// Main root component
+class Root extends Component {
+    static template = "Root";
+
+    setup() {
+        // simple state hook (reactive object)
+        this.counter = useState({ value: 0 });
+
+        // this hooks is bound to the 'mouse' property.
+        this.mouse = useMouse();
+    }
+
+    increment() {
+        this.counter.value++;
+    }
+}
+
+// Application setup
+mount(Root, document.body, { templates: TEMPLATES, dev: true });

docs/playground/samples/custom_hooks/custom_hooks.xml

@@ -0,0 +1,7 @@
+
+<templates>
+  <div t-name="Root">
+    <button t-on-click="increment">Click! <t t-esc="counter.value"/></button>
+    <div>Mouse: <t t-esc="mouse.x"/>, <t t-esc="mouse.y"/></div>
+  </div>
+</templates>

docs/playground/samples/form/form.js

@@ -0,0 +1,22 @@
+// This example illustrate how the t-model directive can be used to synchronize
+// data between html inputs (and select/textareas) and the state of a component.
+// Note that there are two controls with t-model="color": they are totally
+// synchronized.
+import { Component, useState, mount } from "@odoo/owl";
+
+class Form extends Component {
+  static template = "Form";
+
+  setup() {
+    this.state = useState({
+      text: "",
+      othertext: "",
+      number: 11,
+      color: "",
+      bool: false
+    });
+  }
+}
+
+// Application setup
+mount(Form, document.body, { templates: TEMPLATES, dev: true });

docs/playground/samples/form/form.xml

@@ -0,0 +1,37 @@
+<templates>
+  <div t-name="Form">
+    <h1>Form</h1>
+    <div>
+      Text (immediate): <input t-model="state.text"/>
+    </div>
+    <div>
+      Other text (lazy): <input t-model.lazy="state.othertext"/>
+    </div>
+    <div>
+      Number: <input  t-model.number="state.number"/>
+    </div>
+    <div>
+      Boolean: <input  type="checkbox" t-model="state.bool"/>
+    </div>
+    <div>
+      Color, with a select:
+      <select  t-model="state.color">
+        <option value="">Select a color</option>
+        <option value="red">Red</option>
+        <option value="blue">Blue</option>
+      </select>
+    </div>
+    <div>
+      Color, 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>
+    <hr/>
+    <h1>State</h1>
+    <div>Text: <t t-esc="state.text"/></div>
+    <div>Other Text: <t t-esc="state.othertext"/></div>
+    <div>Number: <t t-esc="state.number"/></div>
+    <div>Boolean: <t t-if="state.bool">True</t><t t-else="">False</t></div>
+    <div>Color: <t t-esc="state.color"/></div>
+  </div>
+</templates>

docs/playground/samples/jsconfig.json

@@ -0,0 +1,7 @@
+{
+    "compilerOptions": {
+        "paths": {
+            "owl": ["../../../src/index.ts"],
+        },
+    }
+}

docs/playground/samples/lifecycle_demo/lifecycle_demo.css

@@ -0,0 +1,11 @@
+button {
+    font-size: 18px;
+    margin: 5px;
+}
+
+.demo {
+    margin: 10px;
+    padding: 10px;
+    background-color: #dddddd;
+    width: 250px;
+}

docs/playground/samples/lifecycle_demo/lifecycle_demo.js

@@ -0,0 +1,68 @@
+// This example shows all the possible lifecycle hooks
+//
+// The root component controls a sub component (DemoComponent). It logs all its lifecycle
+// methods in the console.  Try modifying its state by clicking on it, or by
+// clicking on the two main buttons, and look into the console to see what
+// happens.
+import {
+    Component,
+    useState,
+    mount,
+    useComponent,
+    onWillStart,
+    onMounted,
+    onWillUnmount,
+    onWillUpdateProps,
+    onPatched,
+    onWillPatch,
+    onWillRender,
+    onRendered,
+    onWillDestroy,
+} from "@odoo/owl";
+  
+function useLogLifecycle() {
+    const component = useComponent();
+    const name = component.constructor.name;
+    onWillStart(() => console.log(`${name}:willStart`));
+    onMounted(() => console.log(`${name}:mounted`));
+    onWillUpdateProps(() => console.log(`${name}:willUpdateProps`));
+    onWillRender(() => console.log(`${name}:willRender`));
+    onRendered(() => console.log(`${name}:rendered`));
+    onWillPatch(() => console.log(`${name}:willPatch`));
+    onPatched(() => console.log(`${name}:patched`));
+    onWillUnmount(() => console.log(`${name}:willUnmount`));
+    onWillDestroy(() => console.log(`${name}:willDestroy`));
+}
+
+class DemoComponent extends Component {
+    static template = "DemoComponent";
+
+    setup() {
+        useLogLifecycle();
+        this.state = useState({ n: 0 });
+    }
+    increment() {
+        this.state.n++;
+    }
+}
+
+class Root extends Component {
+    static template = "Root";
+    static components = { DemoComponent };
+
+    setup() {
+        useLogLifecycle();
+        this.state = useState({ n: 0, flag: true });
+    }
+
+    increment() {
+        this.state.n++;
+    }
+
+    toggleSubComponent() {
+        this.state.flag = !this.state.flag;
+    }
+}
+
+mount(Root, document.body, { templates: TEMPLATES, dev: true });
+  

docs/playground/samples/lifecycle_demo/lifecycle_demo.xml

@@ -0,0 +1,15 @@
+<templates>
+  <div t-name="DemoComponent" t-on-click="increment" class="demo">
+    <div>Demo Sub Component</div>
+    <div>(click on me to update me)</div>
+    <div>Props: <t t-esc="props.n"/>, State: <t t-esc="state.n"/>. </div>
+  </div>
+
+  <div t-name="Root">
+    <button t-on-click="increment">Increment Parent State</button>
+    <button t-on-click="toggleSubComponent">Toggle SubComponent</button>
+    <div t-if="state.flag">
+      <DemoComponent n="state.n"/>
+    </div>
+  </div>
+</templates>

docs/playground/samples/responsive_app/responsive_app.css

@@ -0,0 +1,56 @@
+body {
+    margin: 0;
+}
+
+.app {
+    height: 100%;
+    flex-direction: column;
+}
+
+.app.desktop {
+    display: flex;
+}
+
+.navbar {
+    flex: 0 0 30px;
+    height: 30px;
+    background-color: cadetblue;
+    color: white;
+    line-height: 30px;
+}
+
+.controlpanel {
+    flex: 0 0 100px;
+    height: 100px;
+    background-color: #dddddd;
+    padding: 8px;
+}
+
+.content-wrapper {
+    flex: 1 1 auto;
+    position: relative;
+}
+
+.content {
+    display: flex;
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+}
+
+.formview {
+    overflow-y: auto;
+    flex: 1 1 60%;
+    min-height: 200px;
+    padding: 8px;
+}
+
+.chatter {
+    overflow-y: auto;
+    flex: 1 1 40%;
+    background-color: #eeeeee;
+    color: #333333;
+    padding: 8px;
+}

docs/playground/samples/responsive_app/responsive_app.js

@@ -0,0 +1,118 @@
+// In this example, we show how one can design an application that is responsive:
+// its UI is different in mobile mode or in desktop mode.
+//
+// The main idea is to have a "isMobile" key in the environment, then listen
+// to resize events and update the env if needed.  Then, the whole interface
+// will be updated, creating and destroying components as needed.
+//
+// To see this in action, try resizing the window.  The application will switch
+// to mobile mode whenever it has less than 768px.
+import { Component, useState, mount, reactive, useEnv } from "@odoo/owl";
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+function debounce(func, wait, immediate) {
+  let timeout;
+  return function () {
+    const context = this;
+    const args = arguments;
+    function later() {
+      timeout = null;
+      if (!immediate) {
+        func.apply(context, args);
+      }
+    }
+    const callNow = immediate && !timeout;
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+    if (callNow) {
+      func.apply(context, args);
+    }
+  };
+}
+
+//------------------------------------------------------------------------------
+// Responsive hook
+//------------------------------------------------------------------------------
+
+function createUI() {
+  const getIsMobile = () => window.innerWidth <= 768;
+
+  const ui = reactive({ isMobile: getIsMobile() });
+
+    const updateEnv = debounce(() => {
+      const isMobile = getIsMobile();
+        if (ui.isMobile !== isMobile) {
+            ui.isMobile = isMobile;
+        }
+    }, 15);
+    window.addEventListener("resize", updateEnv);
+    return ui;
+}
+
+function useUI() {
+  const env = useEnv();
+  return useState(env.ui);
+}
+
+
+//------------------------------------------------------------------------------
+// Components
+//------------------------------------------------------------------------------
+class Navbar extends Component {
+  static template = "Navbar";
+}
+
+class MobileSearchView extends Component {
+  static template = "MobileSearchView";
+}
+
+class ControlPanel extends Component {
+  static template = "ControlPanel";
+  static components = { MobileSearchView };
+  setup() {
+    this.ui = useUI();
+  }
+}
+
+class AdvancedComponent extends Component {
+  static template = "AdvancedComponent";
+}
+
+class FormView extends Component {
+  static template = "FormView";
+  static components = { AdvancedComponent };
+  setup() {
+    this.ui = useUI();
+  }
+}
+
+class Chatter extends Component {
+    static template = "Chatter";
+
+    setup() {
+        this.messages = Array.from(Array(100).keys());
+    }
+}
+
+class Root extends Component {
+  static template = "Root";
+  static components = { Navbar, ControlPanel, FormView, Chatter };
+
+  setup() {
+    this.ui = useUI();
+  }
+}
+
+
+
+//------------------------------------------------------------------------------
+// Application Startup
+//------------------------------------------------------------------------------
+const env = {
+  ui: createUI()
+};
+
+mount(Root, document.body, { templates: TEMPLATES, env, dev: true });

docs/playground/samples/responsive_app/responsive_app.xml

@@ -0,0 +1,42 @@
+<templates>
+  <div t-name="Navbar" class="navbar">Navbar</div>
+
+  <div t-name="ControlPanel" class="controlpanel">
+    <h2>Control Panel</h2>
+    <MobileSearchView t-if="ui.isMobile" />
+  </div>
+
+  <div t-name="FormView" class="formview">
+    <h2>Form View</h2>
+    <AdvancedComponent t-if="!ui.isMobile" />
+  </div>
+
+  <div t-name="Chatter" class="chatter">
+    <h2>Chatter</h2>
+    <t t-foreach="messages" t-as="item" t-key="item"><div>Message <t t-esc="item"/></div></t>
+  </div>
+
+  <div t-name="MobileSearchView">Mobile searchview</div>
+
+  <div t-name="AdvancedComponent">
+    This component is only created in desktop mode.
+    <button>Button!</button>
+  </div>
+
+  <t t-name="maincontent">
+    <FormView />
+    <Chatter />
+  </t>
+  <div t-name="Root" class="app" t-att-class="{mobile: ui.isMobile, desktop: !ui.isMobile}">
+    <Navbar/>
+    <ControlPanel/>
+    <div class="content-wrapper" t-if="!ui.isMobile">
+      <div class="content">
+        <t t-call="maincontent"/>
+      </div>
+    </div>
+    <t t-else="">
+      <t t-call="maincontent"/>
+    </t>
+  </div>
+</templates>

docs/playground/samples/single_file_component/single_file_component.js

@@ -0,0 +1,28 @@
+// This example illustrates how one can write Owl components with
+// inline templates.
+
+import { Component, useState, xml, mount } from "@odoo/owl";
+
+// Counter component
+class Counter extends Component {
+  static template = xml`
+    <button t-on-click="() => state.value++">
+      Click! [<t t-esc="state.value"/>]
+    </button>`;
+
+  state = useState({ value: 0 })
+}
+
+// Root
+class Root extends Component {
+  static template = xml`
+    <div>
+      <Counter/>
+      <Counter/>
+    </div>`;
+  
+  static components = { Counter };
+}
+
+// Application setup
+mount(Root, document.body, { templates: TEMPLATES, dev: true});

docs/playground/samples/slots/slots.css

@@ -0,0 +1,43 @@
+.main {
+    display: flex;
+}
+
+.card {
+    display: flex;
+    flex-direction: column;
+    background-color: #eeeeee;
+    width: 200px;
+    height: 100px;
+    margin: 10px;
+    border: 1px solid gray;
+}
+
+.card.full {
+    height: 100px;
+}
+
+.card.small {
+    height: 25px;
+}
+
+.card-title {
+    flex: 0 0 25px;
+    font-weight: bold;
+    background-color: darkcyan;
+    color: white;
+    padding: 2px;
+}
+
+.card-title button {
+    float: right;
+}
+
+.card-content {
+    flex: 1 1 auto;
+    padding: 5px;
+    border-top: 1px solid white;
+}
+
+.card-footer {
+    border-top: 1px solid white;
+}

docs/playground/samples/slots/slots.js

@@ -0,0 +1,49 @@
+// We show here how slots can be used to create generic components.
+// In this example, the Card component is basically only a container. It is not
+// aware of its content. It just knows where it should be (with t-slot).
+// The parent component define the content with t-set-slot.
+//
+// Note that the t-on-click event, defined in the Root template, is executed in
+// the context of the Root component, even though it is inside the Card component
+import { Component, useState, mount } from "@odoo/owl";
+
+class Card extends Component {
+  static template = "Card";
+  
+  setup() {
+    this.state = useState({ showContent: true });
+  }
+
+  toggleDisplay() {
+    this.state.showContent = !this.state.showContent;
+  }
+}
+
+class Counter extends Component {
+  static template = "Counter";
+  
+  setup() {
+    this.state = useState({val: 1});
+  }
+
+  inc() {
+    this.state.val++;
+  }
+}
+
+// Main root component
+class Root extends Component {
+  static template = "Root"
+  static components = { Card, Counter };
+  
+  setup() {
+    this.state = useState({a: 1, b: 3});
+  }
+
+  inc(key, delta) {
+    this.state[key] += delta;
+  }
+}
+
+// Application setup
+mount(Root, document.body, { templates: TEMPLATES, dev: true});

docs/playground/samples/slots/slots.xml

@@ -0,0 +1,33 @@
+<templates>
+  <div t-name="Card" class="card" t-att-class="state.showContent ? 'full' : 'small'">
+    <div class="card-title">
+      <t t-esc="props.title"/><button t-on-click="toggleDisplay">Toggle</button>
+    </div>
+    <t t-if="state.showContent">
+      <div class="card-content" >
+        <t t-slot="content"/>
+      </div>
+      <div class="card-footer">
+        <t t-slot="footer"/>
+      </div>
+    </t>
+  </div>
+
+  <div t-name="Counter">
+    <t t-esc="state.val"/><button t-on-click="inc">Inc</button>
+  </div>
+
+  <div t-name="Root" class="main">
+    <Card title="'Title card A'">
+      <t t-set-slot="content">Content of card 1...  [<t t-esc="state.a"/>]</t>
+      <t t-set-slot="footer"><button t-on-click="() => this.inc('a', 1)">Increment A</button></t>
+    </Card>
+    <Card title="'Title card B'">
+      <t t-set-slot="content">
+        <div>Card 2... [<t t-esc="state.b"/>]</div>
+        <Counter />
+      </t>
+      <t t-set-slot="footer"><button t-on-click="() => this.inc('b', -1)">Decrement B</button></t>
+    </Card>
+  </div>
+</templates>

docs/playground/samples/todo_app/todo_app.css

@@ -0,0 +1,379 @@
+html,body {
+  margin: 0;
+  padding: 0;
+}
+
+button {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  font-size: 100%;
+  vertical-align: baseline;
+  font-family: inherit;
+  font-weight: inherit;
+  color: inherit;
+  -webkit-appearance: none;
+  appearance: none;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  font: 14px "Helvetica Neue", Helvetica, Arial, sans-serif;
+  line-height: 1.4em;
+  background: #f5f5f5;
+  color: #4d4d4d;
+  min-width: 230px;
+  max-width: 550px;
+  margin: 0 auto;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  font-weight: 300;
+}
+
+:focus {
+  outline: 0;
+}
+
+.hidden {
+  display: none;
+}
+
+.todoapp {
+  background: #fff;
+  margin: 130px 0 40px 0;
+  position: relative;
+  box-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.2), 0 25px 50px 0 rgba(0, 0, 0, 0.1);
+}
+
+.todoapp input::-webkit-input-placeholder {
+  font-style: italic;
+  font-weight: 300;
+  color: #e6e6e6;
+}
+
+.todoapp input::-moz-placeholder {
+  font-style: italic;
+  font-weight: 300;
+  color: #e6e6e6;
+}
+
+.todoapp input::input-placeholder {
+  font-style: italic;
+  font-weight: 300;
+  color: #e6e6e6;
+}
+
+.todoapp h1 {
+  position: absolute;
+  top: -155px;
+  width: 100%;
+  font-size: 100px;
+  font-weight: 100;
+  text-align: center;
+  color: rgba(175, 47, 47, 0.15);
+  -webkit-text-rendering: optimizeLegibility;
+  -moz-text-rendering: optimizeLegibility;
+  text-rendering: optimizeLegibility;
+}
+
+.new-todo,
+.edit {
+  position: relative;
+  margin: 0;
+  width: 100%;
+  font-size: 24px;
+  font-family: inherit;
+  font-weight: inherit;
+  line-height: 1.4em;
+  border: 0;
+  color: inherit;
+  padding: 6px;
+  border: 1px solid #999;
+  box-shadow: inset 0 -1px 5px 0 rgba(0, 0, 0, 0.2);
+  box-sizing: border-box;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+.new-todo {
+  padding: 16px 16px 16px 60px;
+  border: none;
+  background: rgba(0, 0, 0, 0.003);
+  box-shadow: inset 0 -2px 1px rgba(0, 0, 0, 0.03);
+}
+
+.main {
+  position: relative;
+  z-index: 2;
+  border-top: 1px solid #e6e6e6;
+}
+
+.toggle-all {
+  width: 1px;
+  height: 1px;
+  border: none; /* Mobile Safari */
+  opacity: 0;
+  position: absolute;
+  right: 100%;
+  bottom: 100%;
+}
+
+.toggle-all + label {
+  width: 60px;
+  height: 34px;
+  font-size: 0;
+  position: absolute;
+  top: -52px;
+  left: -13px;
+  -webkit-transform: rotate(90deg);
+  transform: rotate(90deg);
+}
+
+.toggle-all + label:before {
+  content: "❯";
+  font-size: 22px;
+  color: #e6e6e6;
+  padding: 10px 27px 10px 27px;
+}
+
+.toggle-all:checked + label:before {
+  color: #737373;
+}
+
+.todo-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.todo-list li {
+  position: relative;
+  font-size: 24px;
+  border-bottom: 1px solid #ededed;
+}
+
+.todo-list li:last-child {
+  border-bottom: none;
+}
+
+.todo-list li.editing {
+  border-bottom: none;
+  padding: 0;
+}
+
+.todo-list li.editing .edit {
+  display: block;
+  width: calc(100% - 43px);
+  padding: 12px 16px;
+  margin: 0 0 0 43px;
+}
+
+.todo-list li.editing .view {
+  display: none;
+}
+
+.todo-list li .toggle {
+  text-align: center;
+  width: 40px;
+  /* auto, since non-WebKit browsers doesn't support input styling */
+  height: auto;
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  margin: auto 0;
+  border: none; /* Mobile Safari */
+  -webkit-appearance: none;
+  appearance: none;
+}
+
+.todo-list li .toggle {
+  opacity: 0;
+}
+
+.todo-list li .toggle + label {
+  /*
+        Firefox requires \`#\` to be escaped - https://bugzilla.mozilla.org/show_bug.cgi?id=922433
+        IE and Edge requires *everything* to be escaped to render, so we do that instead of just the \`#\` - https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/7157459/
+    */
+  background-image: url("data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%2240%22%20height%3D%2240%22%20viewBox%3D%22-10%20-18%20100%20135%22%3E%3Ccircle%20cx%3D%2250%22%20cy%3D%2250%22%20r%3D%2250%22%20fill%3D%22none%22%20stroke%3D%22%23ededed%22%20stroke-width%3D%223%22/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: center left;
+}
+
+.todo-list li .toggle:checked + label {
+  background-image: url("data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%2240%22%20height%3D%2240%22%20viewBox%3D%22-10%20-18%20100%20135%22%3E%3Ccircle%20cx%3D%2250%22%20cy%3D%2250%22%20r%3D%2250%22%20fill%3D%22none%22%20stroke%3D%22%23bddad5%22%20stroke-width%3D%223%22/%3E%3Cpath%20fill%3D%22%235dc2af%22%20d%3D%22M72%2025L42%2071%2027%2056l-4%204%2020%2020%2034-52z%22/%3E%3C/svg%3E");
+}
+
+.todo-list li label {
+  word-break: break-all;
+  padding: 15px 15px 15px 60px;
+  display: block;
+  line-height: 1.2;
+  transition: color 0.4s;
+}
+
+.todo-list li.completed label {
+  color: #d9d9d9;
+  text-decoration: line-through;
+}
+
+.todo-list li .destroy {
+  display: none;
+  position: absolute;
+  top: 0;
+  right: 10px;
+  bottom: 0;
+  width: 40px;
+  height: 40px;
+  margin: auto 0;
+  font-size: 30px;
+  color: #cc9a9a;
+  margin-bottom: 11px;
+  transition: color 0.2s ease-out;
+}
+
+.todo-list li .destroy:hover {
+  color: #af5b5e;
+}
+
+.todo-list li .destroy:after {
+  content: "×";
+}
+
+.todo-list li:hover .destroy {
+  display: block;
+}
+
+.todo-list li .edit {
+  display: none;
+}
+
+.todo-list li.editing:last-child {
+  margin-bottom: -1px;
+}
+
+.footer {
+  color: #777;
+  padding: 10px 15px;
+  height: 20px;
+  text-align: center;
+  border-top: 1px solid #e6e6e6;
+}
+
+.footer:before {
+  content: "";
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: 50px;
+  overflow: hidden;
+  box-shadow: 0 1px 1px rgba(0, 0, 0, 0.2), 0 8px 0 -3px #f6f6f6,
+    0 9px 1px -3px rgba(0, 0, 0, 0.2), 0 16px 0 -6px #f6f6f6,
+    0 17px 2px -6px rgba(0, 0, 0, 0.2);
+}
+
+.todo-count {
+  float: left;
+  text-align: left;
+}
+
+.todo-count strong {
+  font-weight: 300;
+}
+
+.filters {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  position: absolute;
+  right: 0;
+  left: 0;
+}
+
+.filters li {
+  display: inline;
+}
+
+.filters li a {
+  color: inherit;
+  margin: 3px;
+  padding: 3px 7px;
+  text-decoration: none;
+  border: 1px solid transparent;
+  border-radius: 3px;
+}
+
+.filters li a:hover {
+  border-color: rgba(175, 47, 47, 0.1);
+}
+
+.filters li a.selected {
+  border-color: rgba(175, 47, 47, 0.2);
+}
+
+.clear-completed,
+html .clear-completed:active {
+  float: right;
+  position: relative;
+  line-height: 20px;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.clear-completed:hover {
+  text-decoration: underline;
+}
+
+.info {
+  margin: 65px auto 0;
+  color: #bfbfbf;
+  font-size: 10px;
+  text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
+  text-align: center;
+}
+
+.info p {
+  line-height: 1;
+}
+
+.info a {
+  color: inherit;
+  text-decoration: none;
+  font-weight: 400;
+}
+
+.info a:hover {
+  text-decoration: underline;
+}
+
+/*
+    Hack to remove background from Mobile Safari.
+    Can't use it globally since it destroys checkboxes in Firefox
+*/
+@media screen and (-webkit-min-device-pixel-ratio: 0) {
+  .toggle-all,
+  .todo-list li .toggle {
+    background: none;
+  }
+
+  .todo-list li .toggle {
+    height: 40px;
+  }
+}
+
+@media (max-width: 430px) {
+  .footer {
+    height: 50px;
+  }
+
+  .filters {
+    bottom: 10px;
+  }
+}
+
+.filters a {
+    cursor: pointer;
+}

docs/playground/samples/todo_app/todo_app.js

@@ -0,0 +1,178 @@
+// This example is an implementation of the TodoList application, from the
+// www.todomvc.com project.  This is a non trivial application with some
+// interesting user interactions. It uses the local storage for persistence.
+//
+// In this implementation, we use the owl reactivity mechanism.
+import { Component, useState, mount, useRef, reactive, useEnv, useEffect } from "@odoo/owl";
+
+//------------------------------------------------------------------------------
+// Constants, helpers
+//------------------------------------------------------------------------------
+const ENTER_KEY = 13;
+const ESC_KEY = 27;
+
+function useAutofocus(name) {
+    let ref = useRef(name);
+    useEffect(el => el && el.focus(), () => [ref.el]);
+}
+
+function useStore() {
+    const env = useEnv();
+    return useState(env.store);
+}
+
+//------------------------------------------------------------------------------
+// Task store
+//------------------------------------------------------------------------------
+class TaskList {
+    constructor(tasks) {
+        this.tasks = tasks || [];
+        const taskIds = this.tasks.map((t) => t.id);
+        this.nextId = taskIds.length ? Math.max(...taskIds) + 1 : 1;
+    }
+
+    addTask(text) {
+        text = text.trim();
+        if (text) {
+            const task = {
+                id: this.nextId++,
+                text: text,
+                isCompleted: false,
+            };
+            this.tasks.push(task);
+        }
+    }
+
+    toggleTask(id) {
+        const task = this.tasks.find(t => t.id === id);
+        task.isCompleted = !task.isCompleted;
+    }
+
+    toggleAll(value) {
+        for (let task of this.tasks) {
+            task.isCompleted = value;
+        }
+    }
+    
+    clearCompleted() {
+        const tasks = this.tasks.filter(t => t.isCompleted);
+        for (let task of tasks) {
+            this.deleteTask(task.id);
+        }
+    }
+    
+    deleteTask(id) {
+        const index = this.tasks.findIndex((t) => t.id === id);
+        this.tasks.splice(index, 1);
+    }
+    
+    updateTask(id, text) {
+        const value = text.trim();
+        if (!value) {
+            this.deleteTask(id);
+        } else {
+            const task = this.tasks.find(t => t.id === id);
+            task.text = value;
+        }
+    }
+}
+
+function createTaskStore() {
+    const saveTasks = () => localStorage.setItem("todoapp", JSON.stringify(taskStore.tasks));
+    const initialTasks = JSON.parse(localStorage.getItem("todoapp") || "[]");
+    const taskStore = reactive(new TaskList(initialTasks), saveTasks);
+    saveTasks();
+    return taskStore;
+}
+  
+//------------------------------------------------------------------------------
+// Todo
+//------------------------------------------------------------------------------
+class Todo extends Component {
+    static template = "Todo";
+    
+    setup() {
+        useAutofocus("input");
+        this.store = useStore();
+        this.state = useState({
+            isEditing: false
+        });
+    }
+
+    handleKeyup(ev) {
+        if (ev.keyCode === ENTER_KEY) {
+            this.updateText(ev.target.value);
+        }
+        if (ev.keyCode === ESC_KEY) {
+            ev.target.value = this.props.text;
+            this.state.isEditing = false;
+        }
+    }
+
+    handleBlur(ev) {
+        this.updateText(ev.target.value);
+    }
+
+    updateText(text) {
+        this.store.updateTask(this.props.id, text);
+        this.state.isEditing = false;
+    }
+}
+
+//------------------------------------------------------------------------------
+// TodoList
+//------------------------------------------------------------------------------
+class TodoList extends Component {
+    static template = "TodoList";
+    static components = { Todo };
+    
+    setup() {
+        this.store = useStore();
+        this.state = useState({ filter: "all" });
+    }
+
+    get displayedTasks() {
+      const tasks = this.store.tasks;
+      switch (this.state.filter) {
+        case "active":
+          return tasks.filter((t) => !t.isCompleted);
+        case "completed":
+          return tasks.filter((t) => t.isCompleted);
+        case "all":
+          return tasks;
+      }
+    }
+    
+    get allChecked() {
+        return this.store.tasks.every(todo => todo.isCompleted);
+    }
+
+    get remaining() {
+        return this.store.tasks.filter(todo => !todo.isCompleted).length;
+    }
+
+    get remainingText() {
+        const items = this.remaining < 2 ? "item" : "items";
+        return ` ${items} left`;
+    }
+
+    addTodo(ev) {
+        if (ev.keyCode === ENTER_KEY) {
+            const text = ev.target.value;
+            if (text.trim()) {
+                this.store.addTask(text);
+            }
+            ev.target.value = "";
+        }
+    }
+
+    setFilter(filter) {
+        this.state.filter = filter;
+    }
+}
+
+//------------------------------------------------------------------------------
+// App Initialization
+//------------------------------------------------------------------------------
+const env = { store: createTaskStore() };
+mount(TodoList, document.body, { env, templates: TEMPLATES, dev: true });

docs/playground/samples/todo_app/todo_app.xml

@@ -0,0 +1,50 @@
+<templates>
+  <section t-name="TodoList" class="todoapp">
+    <header class="header">
+      <h1>todos</h1>
+      <input class="new-todo" autofocus="true" autocomplete="off" placeholder="What needs to be done?" t-on-keyup="addTodo"/>
+    </header>
+    <section class="main" t-if="store.tasks.length">
+      <input class="toggle-all" id="toggle-all" type="checkbox" t-att-checked="allChecked" t-on-click="() => store.toggleAll(!allChecked)"/>
+      <label for="toggle-all"></label>
+      <ul class="todo-list">
+        <t t-foreach="displayedTasks" t-as="todo" t-key="todo.id">
+          <Todo id="todo.id" isCompleted="todo.isCompleted" text="todo.text"/>
+        </t>
+      </ul>
+    </section>
+    <footer class="footer" t-if="store.tasks.length">
+      <span class="todo-count">
+        <strong>
+            <t t-esc="remaining"/>
+        </strong>
+        <t t-esc="remainingText"/>
+      </span>
+      <ul class="filters">
+        <li>
+          <a t-on-click="() => this.setFilter('all')" t-att-class="{selected: state.filter === 'all'}">All</a>
+        </li>
+        <li>
+          <a t-on-click="() => this.setFilter('active')" t-att-class="{selected: state.filter === 'active'}">Active</a>
+        </li>
+        <li>
+          <a t-on-click="() => this.setFilter('completed')" t-att-class="{selected: state.filter === 'completed'}">Completed</a>
+        </li>
+      </ul>
+      <button class="clear-completed" t-if="store.tasks.length gt remaining" t-on-click="() => store.clearCompleted()">
+        Clear completed
+      </button>
+    </footer>
+  </section>
+
+  <li t-name="Todo" class="todo" t-att-class="{completed: props.isCompleted, editing: state.isEditing}">
+    <div class="view">
+      <input class="toggle" type="checkbox" t-on-change="() => store.toggleTask(props.id)" t-att-checked="props.completed"/>
+      <label t-on-dblclick="() => state.isEditing = true">
+        <t t-esc="props.text"/>
+      </label>
+      <button class="destroy" t-on-click="() => store.deleteTask(props.id)"></button>
+    </div>
+    <input class="edit" t-ref="input" t-if="state.isEditing" t-att-value="props.text" t-on-keyup="handleKeyup" t-on-blur="handleBlur"/>
+  </li>
+</templates>

docs/playground/samples/window_manager/window_manager.css

@@ -0,0 +1,70 @@
+body {
+    margin: 0;
+}
+
+.app {
+    width: 100%;
+    height: 100%;
+    display: grid;
+    grid-template-rows: auto 50px;
+}
+
+.window-manager {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    background-color: #eeeeee;
+    overflow: hidden;
+}
+
+.menubar {
+    background-color: #875a7b;
+    color: white;
+}
+
+.menubar button {
+    height: 40px;
+    font-size: 18px;
+    margin: 5px;
+}
+
+.window {
+    display: grid;
+    grid-template-rows: 30px auto;
+    border: 1px solid gray;
+    background-color: white;
+    position: absolute;
+    box-shadow: 1px 1px 2px 1px grey;
+}
+
+.window.dragging {
+    opacity: 0.75;
+}
+
+.window .header {
+    background-color: #875a7b;
+    display: grid;
+    grid-template-columns: auto 24px;
+    color: white;
+    line-height: 30px;
+    padding-left: 5px;
+    cursor: default;
+    user-select: none;
+}
+
+.window .header .close {
+    cursor: pointer;
+    font-size: 22px;
+    padding-left: 4px;
+    padding-right: 4px;
+    font-weight: bold;
+}
+
+.counter {
+    font-size: 20px;
+}
+.counter button {
+    width: 80px;
+    height:40px;
+    font-size: 20px;
+}

docs/playground/samples/window_manager/window_manager.js

@@ -0,0 +1,192 @@
+// This example is slightly more complex than usual. We demonstrate
+// here a way to manage sub windows in Owl, declaratively. This is still just a
+// demonstration. Managing windows can be as complex as we want.  For example,
+// we could implement the following features:
+// - resizing windows
+// - minimizing windows
+// - configuration options for windows to make a window non resizeable
+// - minimal width/height
+// - better heuristic for initial window position
+// - ...
+import { Component, useState, mount, useRef, reactive, useEnv, onMounted } from "@odoo/owl";
+
+// -----------------------------------------------------------------------------
+// Window manager code
+// -----------------------------------------------------------------------------
+
+class WindowManager {
+  // contains all components with metadata
+  static Windows = {};
+  windows = {}; // mapping id => info
+  nextId = 1;
+
+  add(type) {
+    const Comp = WindowManager.Windows[type];
+    const left = 50 + Math.round(Math.random()*(window.innerWidth - 50 - Comp.defaultWidth));
+    const top = 50 + Math.round(Math.random()*(window.innerHeight - 100 - Comp.defaultHeight));
+    const id = this.nextId++;
+    this.windows[id] = {
+      id, 
+      title: Comp.defaultTitle,
+      width: Comp.defaultWidth,
+      height: Comp.defaultHeight,
+      left,
+      top,
+      Component: Comp,
+    };
+  }
+  
+  close(id) {
+    delete this.windows[id];
+  }
+
+  updatePosition(id, left, top) {
+    const w = this.windows[id];
+    w.left = left;
+    w.top = top;
+  }
+
+  getWindows() {
+    return Object.values(this.windows);
+  }
+}
+
+function createWindowService() {
+  return reactive(new WindowManager());
+}
+
+function useWindowService() {
+  const env = useEnv();
+  return useState(env.windowService);
+}
+
+// -----------------------------------------------------------------------------
+// Generic Window Component
+// -----------------------------------------------------------------------------
+
+class Window extends Component {
+  static template = "Window";
+  static nextZIndex = 1;
+  zIndex = 0;
+
+  setup() {
+    this.windowService = useWindowService();
+    this.root = useRef('root');
+    onMounted(this.updateZIndex);
+  }
+
+  get style() {
+    let { width, height, top, left } = this.props.info;
+    return `width: ${width}px;height: ${height}px;top:${top}px;left:${left}px;z-index:${this.zIndex}`;
+  }
+
+  close() {
+    this.windowService.close(this.props.info.id);
+  }
+
+  startDragAndDrop(ev) {
+    this.updateZIndex();
+    const self = this;
+    const root = this.root;
+
+    const el = root.el;
+    el.classList.add('dragging');
+
+    const current = this.props.info;
+    const offsetX = current.left - ev.pageX;
+    const offsetY = current.top - ev.pageY;
+    let left, top;
+
+    window.addEventListener("mousemove", moveWindow);
+    window.addEventListener("mouseup", stopDnD, { once: true });
+
+    function moveWindow(ev) {
+      left = Math.max(offsetX + ev.pageX, 0);
+      top = Math.max(offsetY + ev.pageY, 0);
+      el.style.left = `${left}px`;
+      el.style.top = `${top}px`;
+    }
+    function stopDnD() {
+      window.removeEventListener("mousemove", moveWindow);
+      el.classList.remove('dragging');
+
+      if (top !== undefined && left !== undefined) {
+        self.windowService.updatePosition(current.id, left, top);
+      }
+    }
+  }
+
+  updateZIndex() {
+    this.zIndex = Window.nextZIndex++;
+    this.root.el.style['z-index'] = this.zIndex;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Two concrete Window type implementations
+// -----------------------------------------------------------------------------
+
+class HelloWorld extends Component {
+  static template = "HelloWorld";
+  static defaultTitle = "Hello Owl!";
+  static defaultWidth = 200;
+  static defaultHeight = 100;
+}
+
+
+class Counter extends Component {
+  static template = "Counter";
+  static defaultTitle = "Click Counter";
+  static defaultWidth = 300;
+  static defaultHeight = 120;
+  
+  state = useState({ value: 0 });
+  
+  inc() {
+    this.state.value++;
+  }
+}
+
+// register window components
+WindowManager.Windows.Hello = HelloWorld;
+WindowManager.Windows.Counter = Counter;
+
+// -----------------------------------------------------------------------------
+// Window Container
+// -----------------------------------------------------------------------------
+
+class WindowContainer extends Component {
+  static template = "WindowContainer";
+  static components = { Window };
+    
+  setup() {
+    this.windowService = useWindowService();
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Root Component
+// -----------------------------------------------------------------------------
+
+class Root extends Component {
+  static template = "Root";
+  static components = { WindowContainer };
+    
+  setup() {
+    this.windowService = useWindowService();
+  }
+  
+  addWindow(type) {
+    this.windowService.add(type);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Setup
+// -----------------------------------------------------------------------------
+
+const env = {
+  windowService: createWindowService(),
+};
+
+mount(Root, document.body, { templates: TEMPLATES, env, dev: true });

docs/playground/samples/window_manager/window_manager.xml

@@ -0,0 +1,32 @@
+<templates>
+  <div t-name="Window" class="window" t-att-style="style" t-on-click="updateZIndex" t-ref="root">
+    <div class="header">
+      <span t-on-mousedown="startDragAndDrop"><t t-esc="props.info.title"/></span>
+      <span class="close" t-on-click.stop="close">×</span>
+    </div>
+    <t t-slot="default"/>
+  </div>
+
+  <div t-name="WindowContainer" class="window-manager">
+    <Window t-foreach="windowService.getWindows()" t-as="w" t-key="w.id" info="w">
+      <t t-component="w.Component"/>
+    </Window>
+  </div>
+
+  <div t-name="Root" class="app">
+    <WindowContainer/>
+    <div class="menubar">
+      <button t-on-click="() => this.addWindow('Hello')">Say Hello</button>
+      <button t-on-click="() => this.addWindow('Counter')">Counter</button>
+    </div>
+  </div>
+
+  <div t-name="HelloWorld">
+    Some content here...
+  </div>
+
+  <div t-name="Counter" class="counter">
+    <button t-on-click="inc">Click</button>
+    <span><t t-esc="state.value"/></span>
+  </div>
+</templates>

docs/playground/standalone_app/app.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+
+import threading
+import time
+
+from http.server import SimpleHTTPRequestHandler, HTTPServer
+
+httpd = None
+def start_server():
+    global httpd
+    SimpleHTTPRequestHandler.extensions_map['.js'] = 'application/javascript'
+    httpd = HTTPServer(('0.0.0.0', 3600), SimpleHTTPRequestHandler)
+    httpd.serve_forever()
+
+url = 'http://127.0.0.1:3600'
+
+if __name__ == "__main__":
+    print("Owl Application")
+    print("---------------")
+    print("Server running on: {}".format(url))
+    threading.Thread(target=start_server, daemon=True).start()
+
+    while True:
+        try:
+            time.sleep(1)
+        except KeyboardInterrupt:
+            httpd.server_close()
+            quit(0)

docs/playground/standalone_app/index.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>OWL App</title>
+    <link rel="icon" href="data:,">
+
+    <link rel="stylesheet" href="app.css">
+    <script type="importmap">{ "imports": { "@odoo/owl": "./owl.js" } }</script>
+    <script type="module" src="app.js"></script>
+  </head>
+  <body>
+    <pre>
+This app requires a web server, simply opening the html file using your browser will not work.
+You can run a simple web server with one of the following:
+- if you have python3 installed, run app.py with python3 or run 'python3 -m http.server' in the app folder
+- if you have node/npm installed, run 'npx serve' in the app folder
+- if you have php installed, run 'php -S localhost:8080 -t .' in the app folder
+    </pre>
+    <script>if (window.location.protocol !== "file:") document.querySelector("pre").remove()</script>
+  </body>
+</html>

docs/playground/templates.xml

@@ -1,5 +1,5 @@
 <templates>
-  <div t-name="TabbedEditor" class="tabbed-editor">
+  <div t-name="TabbedEditor" class="tabbed-editor" t-att-style="props.style">
     <div class="tabBar" t-att-class="{resizeable: props.resizeable}" t-on-mousedown="onMouseDown">
         <t t-foreach="['js', 'xml', 'css']" t-as="tab" t-key="tab">
             <a t-ref="{{tab}}" t-if="props[tab] !== false" t-key="tab" class="tab flash" t-att-class="{active: state.currentTab===tab}" t-on-click="() => setTab(tab)">
@@ -10,18 +10,19 @@
     <div class="code-editor" t-ref="editor"></div>
   </div>
 
-  <div t-name="App" class="playground">
+  <div t-name="Playground" class="playground">
       <div class="left-bar" t-att-class="{split: state.splitLayout}"
            t-att-style="leftPaneStyle">
         <div class="menubar">
           <a class="btn run-code flash" t-on-click="runCode" title="Execute this Code">▶ Run</a>
-          <select t-on-change="setSample">
-            <option t-foreach="SAMPLES" t-as="sample" t-key="sample_index">
+          <select t-on-change="onSampleChange">
+            <option t-foreach="samples" t-as="sample" t-key="sample_index">
               <t t-esc="sample.description"/>
             </option>
           </select>
-          <a class="btn flash" t-on-click="downloadCode" title="Download a Zip with this Code"><i class="fas fa-download"></i></a>
+          <a class="btn flash" t-on-click="exportStandaloneApp" title="Download zip that bundles this app with a tiny python web server"><i class="fas fa-download"></i></a>
           <a class="layout-selector flash" t-on-click="toggleLayout" title="Toggle Layout"><i class="fas"  t-att-class="state.splitLayout ?  'fa-toggle-on' : 'fa-toggle-off'"></i></a>
+          <a class="btn flash share-code" t-on-click="shareCode" title="Copy a link to this playground"><span>Share</span><span class="copied-notification" t-if="state.copied">Copied link to clipboard!</span></a>
         </div>
         <TabbedEditor
             js="state.js"
@@ -36,19 +37,19 @@
              css="state.css"
              xml="state.xml"
              resizeable="true"
-             onUpdatePanelHeight="updatePanelHeight"
+             updatePanelHeight.bind="updatePanelHeight"
              updateCode="updateCode"/>
         </t>
       </div>
       <div class="separator vertical" t-on-mousedown="onMouseDown"/>
-      <div class="right-pane"  t-att-style="rightPaneStyle">
+      <div class="right-pane">
         <div class="welcome" t-if="state.displayWelcome">
           <div>🦉 Odoo Web Library 🦉</div>
           <div>v<t t-esc="version"/></div>
           <div class="url"><a href="https://github.com/odoo/owl">https://github.com/odoo/owl</a></div>
           <div class="note">
-            <p>Note: these examples are using recent features of Javascript, and require a recent browser to work without a transpilation step!
-              For example, it makes use of class fields and class static fields. These examples should work in a recent Chrome version.
+            <p>
+              Note: these examples make use of recent features of Javascript, and require a recent browser to work without a transpilation step! Among other things, it uses class fields and import maps. If you encounter issues, make sure your browser is up to date.
             </p>
           </div>
         </div>

docs/playground/utils.js

@@ -18,12 +18,6 @@ export function debounce(func, wait, immediate) {
   };
 }
 
-export function useBus(bus, evName, cb) {
-  bus.addEventListener(evName, cb);
-  owl.onWillUnmount(() => {
-    bus.removeEventListener(evName, cb);
-  });
-}
 
 const loadedScripts = {};
 

docs/readme.md

@@ -0,0 +1,5 @@
+# Github page and playground
+
+This folder contains the code for owl's [github page](https://odoo.github.io/owl)
+and the owl [playground](https://odoo.github.io/owl/playground/). If you're
+looking for the owl documentation, click [here](/doc)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odoo/owl",
-  "version": "2.0.0-beta-18",
+  "version": "2.8.1",
   "description": "Odoo Web Library (OWL)",
   "main": "dist/owl.cjs.js",
   "module": "dist/owl.es.js",
@@ -9,25 +9,33 @@
     "dist"
   ],
   "engines": {
-    "node": ">=12.18.3"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "build:bundle": "rollup -c --failAfterWarnings",
     "build:runtime": "rollup -c --failAfterWarnings runtime",
     "build:compiler": "rollup -c --failAfterWarnings compiler",
     "build": "npm run build:bundle",
+    "build:devtools": "rollup -c ./tools/devtools/rollup.config.js",
+    "dev:devtools-chrome": "npm run build:devtools -- --config-browser=chrome",
+    "dev:devtools-firefox": "npm run build:devtools -- --config-browser=firefox",
+    "build:devtools-chrome": "npm run dev:devtools-chrome -- --config-env=production",
+    "build:devtools-firefox": "npm run dev:devtools-firefox -- --config-env=production",
     "test": "jest",
-    "test:debug": "node --inspect-brk node_modules/.bin/jest --runInBand --watch --testTimeout=5000000",
+    "test:debug": "node node_modules/.bin/jest --runInBand --watch --testTimeout=5000000",
     "test:watch": "jest --watch",
-    "playground:serve": "python3 tools/server.py || python tools/server.py",
+    "playground:serve": "python3 tools/playground_server.py || python tools/playground_server.py",
     "playground": "npm run build && npm run playground:serve",
     "preplayground:watch": "npm run build",
     "playground:watch": "npm-run-all  --parallel playground:serve \"build:* -- --watch\"",
-    "prettier": "prettier {src/*.ts,src/**/*.ts,tests/*.ts,tests/**/*.ts,doc/*.md,doc/**/*.md} --write",
-    "check-formatting": "prettier {src/*.ts,src/**/*.ts,tests/*.ts,tests/**/*.ts,doc/*.md,doc/**/*.md} --check",
-    "publish": "npm run build && npm publish",
+    "prettier": "prettier {src/*.ts,src/**/*.ts,tests/*.ts,tests/**/*.ts,doc/*.md,doc/**/*.md,tools/devtools/**/*.js} --write",
+    "check-formatting": "prettier {src/*.ts,src/**/*.ts,tests/*.ts,tests/**/*.ts,doc/*.md,doc/**/*.md,tools/devtools/**/*.js} --check",
+    "lint": "eslint src/**/*.ts tests/**/*.ts",
     "release": "node tools/release.js",
-    "compile_templates": "node tools/compile_xml.js"
+    "compile_templates": "node tools/compile_owl_templates.mjs"
+  },
+  "bin": {
+    "compile_owl_templates": "tools/compile_owl_templates.mjs"
   },
   "repository": {
     "type": "git",
@@ -41,27 +49,31 @@
   "homepage": "https://github.com/odoo/owl#readme",
   "devDependencies": {
     "@types/jest": "^27.0.1",
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^14.11.8",
+    "@typescript-eslint/eslint-plugin": "5.48.1",
+    "@typescript-eslint/parser": "5.48.1",
     "chalk": "^3.0.0",
-    "cpx": "^1.5.0",
     "current-git-branch": "^1.1.0",
-    "git-rev-sync": "^1.12.0",
+    "eslint": "8.31.0",
+    "git-rev-sync": "^3.0.2",
     "github-api": "^3.3.0",
     "jest": "^27.1.0",
     "jest-diff": "^27.3.1",
     "jest-environment-jsdom": "^27.1.0",
-    "live-server": "^1.2.1",
     "npm-run-all": "^4.1.5",
     "prettier": "2.4.1",
     "rollup": "^2.56.3",
+    "rollup-plugin-copy": "^3.3.0",
+    "rollup-plugin-delete": "^2.0.0",
     "rollup-plugin-dts": "^4.2.2",
+    "rollup-plugin-execute": "^1.1.1",
+    "rollup-plugin-string": "^3.0.0",
     "rollup-plugin-terser": "^7.0.2",
     "rollup-plugin-typescript2": "^0.31.1",
-    "sass": "^1.16.1",
     "source-map-support": "^0.5.10",
     "ts-jest": "^27.0.5",
-    "typescript": "4.5.2",
-    "uglify-es": "^3.3.9"
+    "typescript": "4.5.2"
   },
   "jest": {
     "testEnvironment": "jsdom",
@@ -89,5 +101,8 @@
   "prettier": {
     "printWidth": 100,
     "endOfLine": "auto"
+  },
+  "dependencies": {
+    "jsdom": "^25.0.1"
   }
 }

roadmap.md

@@ -1,28 +1,9 @@
 # 🦉 OWL Roadmap 🦉
 
-- Current version: 1.4.10
+- Current version: 2.X
 - 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.
-
+Owl is currently stable. No (large) improvements is expected in the near future.
 
+Note that we intend to keep maintaining owl, and as such, improvements and/or
+breaking changes may require a version bump in the future.

rollup.config.js

@@ -1,6 +1,6 @@
 import pkg from "./package.json";
 import git from "git-rev-sync";
-import typescript from 'rollup-plugin-typescript2';
+import typescript from "rollup-plugin-typescript2";
 import { terser } from "rollup-plugin-terser";
 import dts from "rollup-plugin-dts";
 
@@ -12,49 +12,46 @@ const ES_FILENAME = "dist/owl.es.js";
 
 if (pkg.module !== ES_FILENAME || pkg.main !== CJS_FILENAME) {
   throw new Error("package.json has been modified. Build script should be updated accordingly");
-}  
+}
 
 const outro = `
-__info__.version = '${pkg.version}';
 __info__.date = '${new Date().toISOString()}';
 __info__.hash = '${git.short()}';
 __info__.url = 'https://github.com/odoo/owl';
 `;
 
 switch (process.argv[4]) {
-  case "compiler": 
-    input = "src/compiler/index.ts",
-    output = [
-      getConfigForFormat('cjs', 'dist/compiler.js', ''),
-    ]
+  case "compiler":
+    (input = "src/compiler/index.ts"),
+      (output = [getConfigForFormat("cjs", "dist/compiler.js", "")]);
     break;
   case "runtime":
     input = "src/runtime/index.ts";
     output = [
-      getConfigForFormat('esm', addSuffix(ES_FILENAME,  'runtime'), outro),
-      getConfigForFormat('cjs', addSuffix(CJS_FILENAME,  'runtime'), outro),
-      getConfigForFormat('iife', addSuffix(IIFE_FILENAME,  'runtime'), outro),
-      getConfigForFormat('iife', addSuffix(IIFE_FILENAME,  'runtime'), outro, true),
-    ]
+      getConfigForFormat("esm", addSuffix(ES_FILENAME, "runtime"), outro),
+      getConfigForFormat("cjs", addSuffix(CJS_FILENAME, "runtime"), outro),
+      getConfigForFormat("iife", addSuffix(IIFE_FILENAME, "runtime"), outro),
+      getConfigForFormat("iife", addSuffix(IIFE_FILENAME, "runtime"), outro, true),
+    ];
     break;
   default:
-    input = "src/index.ts",
-    output = [
-      getConfigForFormat('esm', ES_FILENAME, outro),
-      getConfigForFormat('cjs', CJS_FILENAME, outro),
-      getConfigForFormat('iife', IIFE_FILENAME, outro),
-      getConfigForFormat('iife', IIFE_FILENAME, outro, true),
-    ]
-  }
+    (input = "src/index.ts"),
+      (output = [
+        getConfigForFormat("esm", ES_FILENAME, outro),
+        getConfigForFormat("cjs", CJS_FILENAME, outro),
+        getConfigForFormat("iife", IIFE_FILENAME, outro),
+        getConfigForFormat("iife", IIFE_FILENAME, outro, true),
+      ]);
+}
 
 /**
  * Generate from a string depicting a path a new path for the minified version.
  * @param {string} pkgFileName file name
  */
 function addSuffix(pkgFileName, suffix) {
-  const parts = pkgFileName.split('.');
+  const parts = pkgFileName.split(".");
   parts.splice(parts.length - 1, 0, suffix);
-  return parts.join('.');
+  return parts.join(".");
 }
 
 /**
@@ -72,7 +69,7 @@ function getConfigForFormat(format, generatedFileName, outro, minified = false)
     outro: outro,
     freeze: false,
     plugins: minified ? [terser()] : [],
-    indent: '    ', // indent with 4 spaces
+    indent: "    ", // indent with 4 spaces
   };
 }
 
@@ -82,9 +79,19 @@ export default [
     output,
     plugins: [
       typescript({
-        useTsconfigDeclarationDir: true
+        useTsconfigDeclarationDir: true,
       }),
-    ]
+    ],
+  },
+  {
+    input: "src/compiler/standalone/index.ts",
+    output: [{ file: "dist/compile_templates.mjs", format: "es" }],
+    external: ["fs", "fs/promises", "path", "jsdom"],
+    plugins: [
+      typescript({
+        useTsconfigDeclarationDir: true,
+      }),
+    ],
   },
   {
     input: "dist/types/index.d.ts",

signal.md

@@ -0,0 +1,18 @@
+# encountered issues
+## dropdown issue
+- there was a problem that writing in a state while the effect was updated.
+  - the tracking of signal being written were dropped because we cleared it
+    after re-running the effect that made a write.
+  - solution: clear the tracked signal before re-executing the effects
+- reading signal A while also writing signal A makes an infinite loop
+  - current solution: use toRaw in order to not track the read
+  - possible better solution to explore: do not track read if there is a write in a effect.
+## website issue
+- a rpc request was made on onWillStart, onWillStart was tracking reads. (see WebsiteBuilderClientAction)
+  - The read subsequently made a write, that re-triggered the onWillStart.
+  - A similar situation happened with onWillUpdateProps (see Transition)
+  - solution: prevent tracking reads in onWillStart and onWillUpdateProps
+
+# future
+- worker for computation?
+- cap'n web

src/common/owl_error.ts

@@ -0,0 +1,4 @@
+// Custom error class that wraps error that happen in the owl lifecycle
+export class OwlError extends Error {
+  cause?: any;
+}

src/common/types.ts

@@ -0,0 +1,28 @@
+export type ExecutionContext = {
+  onReadAtom: (atom: Atom) => void;
+  unsubcribe?: (scheduledContexts: Set<ExecutionContext>) => void;
+  update?: Function;
+  atoms?: Set<Atom>;
+  meta?: any;
+  // getParent: () => ExecutionContext | undefined;
+  // getChildren: () => ExecutionContext[];
+  // schedule: () => void;
+};
+
+export type customDirectives = Record<
+  string,
+  (node: Element, value: string, modifier: string[]) => void
+>;
+
+export type Atom = {
+  executionContexts: Set<ExecutionContext>;
+  dependents: Set<DerivedAtom>;
+  getValue: () => any;
+};
+
+export type OldValue = any;
+
+export type DerivedAtom = Atom & {
+  dependencies: Map<Atom, OldValue>;
+  computed: boolean;
+};