wip

closes #521

doc/learning/testing_components.md

@@ -1,10 +1,9 @@
-# 🦉 Testing and Debugging Owl components 🦉
+# 🦉 Testing Owl components 🦉
 
 ## Content
 
 - [Overview](#overview)
 - [Unit Tests](#unit-tests)
-- [Debugging](#debugging)
 
 ## Overview
 
@@ -131,81 +130,3 @@ function afterUpdates() {
   });
 }
 ```
-
-## Debugging
-
-Non trivial applications become quickly more difficult to understand. It is then
-useful to have a solid understanding of what is going on. To help with that,
-the following code can simply be copy/pasted in an application. Once it is
-executed, it will log a lot of information on each component main hooks.
-
-```js
-let current;
-Object.defineProperty(owl.Component, "current", {
-  get() {
-    return current;
-  },
-  set(comp) {
-    current = comp;
-    const name = comp.constructor.name;
-    let __owl__;
-    Object.defineProperty(current, "__owl__", {
-      get() {
-        return __owl__;
-      },
-      set(val) {
-        __owl__ = val;
-        debugComponent(comp, name, __owl__.id);
-      }
-    });
-  }
-});
-
-function toStr(props) {
-  let str = JSON.stringify(props || {});
-  if (str.length > 200) {
-    str = str.slice(0, 200) + "...";
-  }
-  return str;
-}
-
-function debugComponent(component, name, id) {
-  console.log(`[DEBUG] constructor ${name}<id=${id}>, props=${toStr(component.props)}`);
-  owl.hooks.onWillStart(() => {
-    console.log(`[DEBUG] willStart: '${name}<id=${id}>'`);
-  });
-  owl.hooks.onMounted(() => {
-    console.log(`[DEBUG] mounted: '${name}<id=${id}>'`);
-  });
-  owl.hooks.onWillUpdateProps(nextProps => {
-    console.log(`[DEBUG] willUpdateProps: '${name}<id=${id}> nextprops=${toStr(nextProps)}`);
-  });
-  owl.hooks.onWillPatch(() => {
-    console.log(`[DEBUG] willPatch: '${name}<id=${id}>'`);
-  });
-  owl.hooks.onPatched(() => {
-    console.log(`[DEBUG] patched: '${name}<id=${id}>'`);
-  });
-  owl.hooks.onWillUnmount(() => {
-    console.log(`[DEBUG] willUnmount: '${name}<id=${id}>'`);
-  });
-  const __render = component.__render.bind(component);
-  component.__render = function(...args) {
-    console.log(`[DEBUG] rendering template: '${name}<id=${id}>'`);
-    __render(...args);
-  };
-  const render = component.render.bind(component);
-  component.render = function(...args) {
-    console.log(`[DEBUG] render: '${name}<id=${id}>'`);
-    return render(...args);
-  };
-  const mount = component.mount.bind(component);
-  component.mount = function(...args) {
-    console.log(`[DEBUG] mount: '${name}<id=${id}>'`);
-    return mount(...args);
-  };
-}
-```
-
-Note that it is certainly useful to run this code at some point in an application,
-just to get a feel of what each user action implies, for the framework.

doc/learning/tutorial_todoapp.md

@@ -297,7 +297,7 @@ A lot of stuff happened here:
 - the `Task` component has a `props` key: this is only useful for validation
   purpose. It says that each `Task` should be given exactly one prop, named
   `task`. If this is not the case, Owl will throw an
-  [error](../reference/component.md#props-validation). This is extremely
+  [error](../reference/props_validation.md). This is extremely
   useful when refactoring components
 - finally, to activate the props validation, we need to set Owl's
   [mode](../reference/config.md#mode) to `dev`. This is done in the `setup`

doc/readme.md

@@ -4,6 +4,7 @@
 
 - [Animations](reference/animations.md)
 - [Component](reference/component.md)
+- [Concurrency Model](reference/concurrency_model.md)
 - [Configuration](reference/config.md)
 - [Context](reference/context.md)
 - [Environment](reference/environment.md)
@@ -12,6 +13,7 @@
 - [Miscellaneous Components](reference/misc.md)
 - [Observer](reference/observer.md)
 - [Props](reference/props.md)
+- [Props Validation](reference/props_validation.md)
 - [QWeb Templating Language](reference/qweb_templating_language.md)
 - [QWeb Engine](reference/qweb_engine.md)
 - [Router](reference/router.md)
@@ -23,7 +25,7 @@
 
 - [Quick Start: create an (almost) empty Owl application](learning/quick_start.md)
 - [Tutorial: create a TodoList application](learning/tutorial_todoapp.md)
-- [Testing and Debugging Owl components](learning/testing_components.md)
+- [Testing Owl components](learning/testing_components.md)
 
 ## Miscellaneous
 

doc/reference/component.md

@@ -14,12 +14,9 @@
   - [Composition](#composition)
   - [Event Handling](#event-handling)
   - [Form Input Bindings](#form-input-bindings)
-  - [Semantics](#semantics)
-  - [Props Validation](#props-validation)
   - [References](#references)
   - [Slots](#slots)
   - [Dynamic sub components](#dynamic-sub-components)
-  - [Asynchronous Rendering](#asynchronous-rendering)
   - [Error Handling](#error-handling)
   - [Functional Components](#functional-components)
   - [SVG components](#svg-components)
@@ -204,7 +201,7 @@ to be called in the constructor.
 * **`props`** (Object, optional): if given, this is an object that describes the
   type and shape of the (actual) props given to the component. If Owl mode is
   `dev`, this will be used to validate the props each time the component is
-  created/updated. See [Props Validation](#props-validation) for more information.
+  created/updated. See [Props Validation](props_validation.md) for more information.
 
   ```js
   class Counter extends owl.Component {
@@ -745,196 +742,6 @@ update a number whenever the change is done.
 
 Note: the online playground has an example to show how it works.
 
-### Semantics
-
-We give here an informal description of the way components are created/updated
-in an application. Here, ordered lists describe actions that are executed
-sequentially, bullet lists describe actions that are executed in parallel.
-
-**Scenario 1: initial rendering** Imagine we want to render the following component tree:
-
-```
-        A
-       / \
-      B   C
-         / \
-        D   E
-```
-
-Here is what happen whenever we mount the root
-component (with some code like `app.mount(document.body)`).
-
-1. `willStart` is called on `A`
-
-2. when it is done, template `A` is rendered.
-
-   - component `B` is created
-     1. `willStart` is called on `B`
-     2. template `B` is rendered
-   - component `C` is created
-     1. `willStart` is called on `C`
-     2. template `C` is rendered
-        - component `D` is created
-          1. `willStart` is called on `D`
-          2. template `D` is rendered
-        - component `E` is created
-          1. `willStart` is called on `E`
-          2. template `E` is rendered
-
-3. each components are patched into a detached DOM element, in the following order:
-   `E`, `D`, `C`, `B`, `A`. (so the actual full DOM tree is created
-   in one pass)
-
-4. the component `A` root element is actually appended to `document.body`
-
-5. The method `mounted` is called recursively on all components in the following
-   order: `E`, `D`, `C`, `B`, `A`.
-
-**Scenario 2: rerendering a component**. Now, let's assume that the user clicked on some
-button in `C`, and this results in a state update, which is supposed to:
-
-- update `D`,
-- remove `E`,
-- add new component `F`.
-
-So, the component tree should look like this:
-
-```
-        A
-       / \
-      B   C
-         / \
-        D   F
-```
-
-Here is what Owl will do:
-
-1. because of a state change, the method `render` is called on `C`
-2. template `C` is rendered again
-
-   - component `D` is updated:
-     1. hook `willUpdateProps` is called on `D` (async)
-     2. template `D` is rerendered
-   - component `F` is created:
-     1. hook `willStart` is called on `E` (async)
-     2. template `F` is rendered
-
-3. `willPatch` hooks are called recursively on components `C`, `D` (not on `F`,
-   because it is not mounted yet)
-
-4. components `F`, `D` are patched in that order
-
-5. component `C` is patched, which will cause recursively:
-
-   1. `willUnmount` hook on `E`
-   2. destruction of `E`,
-
-6. `mounted` hook is called on `F`, `patched` hooks are called on `D`, `C`
-
-### Props Validation
-
-As an application becomes complex, it may be quite unsafe to define props in an informal way. This leads to two issues:
-
-- hard to tell how a component should be used, by looking at its code.
-- unsafe, it is easy to send wrong props into a component, either by refactoring a component, or one of its parents.
-
-A props type system solves both issues, by describing the types and shapes
-of the props. Here is how it works in Owl:
-
-- `props` key is a static key (so, different from `this.props` in a component instance)
-- it is optional: it is ok for a component to not define a `props` key.
-- props are validated whenever a component is created/updated
-- props are only validated in `dev` mode (see [config page](config.md#mode))
-- if a key does not match the description, an error is thrown
-- it validates keys defined in (static) `props`. Additional keys given by the
-  parent will cause an error.
-
-For example:
-
-```js
-class ComponentA extends owl.Component {
-    static props = ['id', 'url'];
-
-    ...
-}
-
-class ComponentB extends owl.Component {
-  static props = {
-    count: {type: Number},
-    messages: {
-      type: Array,
-      element: {type: Object, shape: {id: Boolean, text: 'string' }
-    },
-   date: Date,
-   combinedVal: [Number, Boolean]
-  };
-
-  ...
-}
-```
-
-- it is an object or a list of strings
-- a list of strings is a simplified props definition, which only lists the name
-  of the props. Also, if the name ends with `?`, it is considered optional.
-- all props are by default required, unless they are defined with `optional: true`
-  (in that case, validation is only done if there is a value)
-- valid types are: `Number, String, Boolean, Object, Array, Date, Function`, and all
-  constructor functions (so, if you have a `Person` class, it can be used as a type)
-- arrays are homogeneous (all elements have the same type/shape)
-
-For each key, a `prop` definition is either a boolean, a constructor, a list of constructors, or an object:
-
-- a boolean: indicate that the props exists, and is mandatory.
-- a constructor: this should describe the type, for example: `id: Number` describe
-  the props `id` as a number
-- a list of constructors. In that case, this means that we allow more than one
-  type. For example, `id: [Number, String]` means that `id` can be either a string
-  or a number.
-- an object. This makes it possible to have more expressive definition. The following sub keys are then allowed (but not mandatory):
-  - `type`: the main type of the prop being validated
-  - `element`: if the type was `Array`, then the `element` key describes the type of each element in the array. If it is not set, then we only validate the array, not its elements,
-  - `shape`: if the type was `Object`, then the `shape` key describes the interface of the object. If it is not set, then we only validate the object, not its elements,
-  - `validate`: this is a function which should return a boolean to determine if
-    the value is valid or not. Useful for custom validation logic.
-
-Examples:
-
-```js
-  // only the existence of those 3 keys is documented
-  static props = ['message', 'id', 'date'];
-```
-
-```js
-  // size is optional
-  static props = ['message', 'size?'];
-```
-
-```js
-  static props = {
-    messageIds: {type: Array, element: Number},  // list of number
-    otherArr: {type: Array},   // just array. no validation is made on sub elements
-    otherArr2: Array,   // same as otherArr
-    someObj: {type: Object},  // just an object, no internal validation
-    someObj2: {
-      type: Object,
-      shape: {
-        id: Number,
-        name: {type: String, optional: true},
-        url: String
-      ]},    // object, with keys id (number), name (string, optional) and url (string)
-    someFlag: Boolean,     // a boolean, mandatory (even if `false`)
-    someVal: [Boolean, Date],   // either a boolean or a date
-    otherValue: true,     // indicates that it is a prop
-    kindofsmallnumber: {
-      type: Number,
-      validate: n => (0 <= n && n <= 10)
-    },
-    size: {
-      validate:  e => ["small", "medium", "large"].includes(e)
-    },
-  };
-```
-
 ### References
 
 The `useRef` hook is useful when we need a way to interact with some inside part
@@ -1092,49 +899,6 @@ component class.
 
 Note that the `t-component` directive can only be used on `<t>` nodes.
 
-### Asynchronous Rendering
-
-Working with asynchronous code always adds a lot of complexity to a system. Whenever
-different parts of a system are active at the same time, one needs to think
-carefully about all possible interactions. Clearly, this is also true for Owl
-components.
-
-There are two different common problems with Owl asynchronous rendering model:
-
-- any component can delay the rendering (initial and subsequent) of the whole
-  application
-- for a given component, there are two independant situations that will trigger an
-  asynchronous rerendering: a change in the state, or a change in the props.
-  These changes may be done at different times, and Owl has no way of knowing
-  how to reconcile the resulting renderings.
-
-Here are a few tips on how to work with asynchronous components:
-
-1. Minimize the use of asynchronous components!
-2. Maybe move the asynchronous logic in a store, which then triggers (mostly)
-   synchronous renderings
-3. Lazy loading external libraries is a good use case for async rendering. This
-   is mostly fine, because we can assume that it will only takes a fraction of a
-   second, and only once (see [`owl.utils.loadJS`](utils.md#loadjs))
-4. For all the other cases, the [`AsyncRoot`](misc.md#asyncroot) component is there to help you. When
-   this component is met, a new rendering
-   sub tree is created, such that the rendering of that component (and its
-   children) is not tied to the rendering of the rest of the interface. It can
-   be used on an asynchronous component, to prevent it from delaying the
-   rendering of the whole interface, or on a synchronous one, such that its
-   rendering isn't delayed by other (asynchronous) components. Note that this
-   directive has no effect on the first rendering, but only on subsequent ones
-   (triggered by state or props changes).
-
-   ```xml
-   <div t-name="ParentComponent">
-     <SyncChild />
-     <AsyncRoot>
-        <AsyncChild/>
-     </AsyncRoot>
-   </div>
-   ```
-
 ### Error Handling
 
 By default, whenever an error occurs in the rendering of an Owl application, we

doc/reference/concurrency_model.md

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

doc/reference/props_validation.md

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

doc/tooling.md

@@ -6,6 +6,7 @@
 - [Playground](#playground)
 - [Benchmarks](#benchmarks)
 - [Single File Component](#single-file-component)
+- [Debugging Script](#debugging-script)
 
 ## Overview
 
@@ -78,3 +79,29 @@ Note that the above example has an inline xml comment, just after the `xml` call
 This is useful for some editor plugins, such as the VS Code addon
 `Comment tagged template`, which, if installed, add syntax highlighting to the
 content of the template string.
+
+## Debugging Script
+
+## Debugging
+
+Non trivial applications become quickly more difficult to understand. It is then
+useful to have a solid understanding of what is going on. To help with that,
+logging useful information is extremely valuable. There is a [javascript file](../tools/debug.js) which can be evaluated in an application.
+
+Once it is executed, it will log a lot of information on each component main hooks. The following code is a minified version to make it easier to copy/paste:
+
+```
+let debugSetup = {
+  // componentBlackList: /App/,  // regexp
+  // componentWhiteList: /SomeComponent/, // regexp
+  // methodBlackList: ["mounted"], // list of method names
+  // methodWhiteList: ["willStart"], // list of method names
+  logScheduler: false,  // display/mute scheduler logs
+  logStore: true,     // display/mute store logs
+};
+{let o,t="[OWL_DEBUG]";function toStr(o){let t=JSON.stringify(o||{});return t.length>200&&(t=t.slice(0,200)+"..."),t}function debugComponent(o,e,n){let l=`${e}<id=${n}>`,r=o=>(!debugSetup.methodBlackList||!debugSetup.methodBlackList.includes(o))&&!(debugSetup.methodWhiteList&&!debugSetup.methodWhiteList.includes(o));r("constructor")&&console.log(`${t} ${l} constructor, props=${toStr(o.props)}`),r("willStart")&&owl.hooks.onWillStart(()=>{console.log(`${t} ${l} willStart`)}),r("mounted")&&owl.hooks.onMounted(()=>{console.log(`${t} ${l} mounted`)}),r("willUpdateProps")&&owl.hooks.onWillUpdateProps(o=>{console.log(`${t} ${l} willUpdateProps, nextprops=${toStr(o)}`)}),r("willPatch")&&owl.hooks.onWillPatch(()=>{console.log(`${t} ${l} willPatch`)}),r("patched")&&owl.hooks.onPatched(()=>{console.log(`${t} ${l} patched`)}),r("willUnmount")&&owl.hooks.onWillUnmount(()=>{console.log(`${t} ${l} willUnmount`)});const s=o.__render.bind(o);o.__render=function(...o){console.log(`${t} ${l} rendering template`),s(...o)};const u=o.render.bind(o);o.render=function(...o){return console.log(`${t} ${l} render`),u(...o)};const c=o.mount.bind(o);o.mount=function(...o){return console.log(`${t} ${l} mount`),c(...o)}}if(Object.defineProperty(owl.Component,"current",{get:()=>o,set(t){o=t;const e=t.constructor.name;if(debugSetup.componentBlackList&&debugSetup.componentBlackList.test(e))return;if(debugSetup.componentWhiteList&&!debugSetup.componentWhiteList.test(e))return;let n;Object.defineProperty(o,"__owl__",{get:()=>n,set(o){debugComponent(t,e,(n=o).id)}})}}),debugSetup.logScheduler){let o;Object.defineProperty(owl.Component.scheduler,"isRunning",{get:()=>o,set(e){e?console.log(`${t} scheduler: start running tasks queue`):console.log(`${t} scheduler: stop running tasks queue`),o=e}})}if(debugSetup.logStore){let o=owl.Store.prototype.dispatch;owl.Store.prototype.dispatch=function(e,...n){return console.log(`${t} store: action '${e}' dispatched. Payload: '${toStr(n)}'`),o.call(this,e,...n)}}}
+
+```
+
+Note that it is certainly useful to run this code at some point in an application,
+just to get a feel of what each user action implies, for the framework.

src/component/fiber.ts

@@ -180,6 +180,7 @@ export class Fiber {
    */
   complete() {
     let component = this.component;
+    let fiber: Fiber = this;
     this.isCompleted = true;
     if (!this.target && !component.__owl__.isMounted) {
       return;
@@ -194,48 +195,58 @@ export class Fiber {
     this._walk(doWork);
     const patchLen = patchQueue.length;
 
-    // call willPatch hook on each fiber of patchQueue
-    for (let i = 0; i < patchLen; i++) {
-      const fiber = patchQueue[i];
-      if (fiber.shouldPatch) {
+    try {
+      // call willPatch hook on each fiber of patchQueue
+      for (let i = 0; i < patchLen; i++) {
+        fiber = patchQueue[i];
+        if (fiber.shouldPatch) {
+          component = fiber.component;
+          if (component.__owl__.willPatchCB) {
+            component.__owl__.willPatchCB();
+          }
+          component.willPatch();
+        }
+      }
+
+      // call __patch on each fiber of (reversed) patchQueue
+      for (let i = patchLen - 1; i >= 0; i--) {
+        fiber = patchQueue[i];
         component = fiber.component;
-        if (component.__owl__.willPatchCB) {
-          component.__owl__.willPatchCB();
+        component.__patch(fiber.vnode!);
+        if (!fiber.shouldPatch && (!fiber.target || i !== 0)) {
+          component.__owl__.pvnode!.elm = component.__owl__.vnode!.elm;
         }
-        component.willPatch();
+        component.__owl__.currentFiber = null;
       }
-    }
 
-    // call __patch on each fiber of (reversed) patchQueue
-    for (let i = patchLen - 1; i >= 0; i--) {
-      const fiber = patchQueue[i];
-      component = fiber.component;
-      component.__patch(fiber.vnode!);
-      if (!fiber.shouldPatch && (!fiber.target || i !== 0)) {
-        component.__owl__.pvnode!.elm = component.__owl__.vnode!.elm;
+      // insert into the DOM (mount case)
+      let inDOM = false;
+      if (this.target) {
+        this.target.appendChild(this.component.el!);
+        inDOM = document.body.contains(this.target);
       }
-      component.__owl__.currentFiber = null;
-    }
 
-    // insert into the DOM (mount case)
-    let inDOM = false;
-    if (this.target) {
-      this.target.appendChild(this.component.el!);
-      inDOM = document.body.contains(this.target);
-    }
-
-    // call patched/mounted hook on each fiber of (reversed) patchQueue
-    for (let i = patchLen - 1; i >= 0; i--) {
-      const fiber = patchQueue[i];
-      component = fiber.component;
-      if (fiber.shouldPatch && !this.target) {
-        component.patched();
-        if (component.__owl__.patchedCB) {
-          component.__owl__.patchedCB();
+      // call patched/mounted hook on each fiber of (reversed) patchQueue
+      for (let i = patchLen - 1; i >= 0; i--) {
+        fiber = patchQueue[i];
+        component = fiber.component;
+        if (fiber.shouldPatch && !this.target) {
+          component.patched();
+          if (component.__owl__.patchedCB) {
+            component.__owl__.patchedCB();
+          }
+        } else if (this.target ? inDOM : true) {
+          component.__callMounted();
         }
-      } else if (this.target ? inDOM : true) {
-        component.__callMounted();
       }
+    } catch (e) {
+      // if there is no current fiber on component, we are in the situation where
+      // components were patched to the DOM, but a mounted/patched hook threw an
+      // error.  In that case, we cannot manage the error at a lower level than
+      // the root fiber, since some components may not have been properly mounted
+      // patched yet.
+      const errorFiber = component.__owl__.currentFiber ? fiber : this;
+      errorFiber.handleError(e);
     }
   }
 
@@ -274,7 +285,11 @@ export class Fiber {
     qweb.trigger("error", error);
 
     if (canCatch) {
+      // this.root.isCompleted = false
+      this.root.isCompleted = false;
+      // component.__owl__.currentFiber!.root.isCompleted = false;
       component.catchError!(error);
+
     } else {
       // the 3 next lines aim to mark the root fiber as being in error, and
       // to force it to end, without waiting for its children

src/component/scheduler.ts

@@ -62,10 +62,9 @@ export class Scheduler {
       }
       if (task.fiber.counter === 0) {
         if (!task.fiber.error) {
-          try {
-            task.fiber.complete();
-          } catch (e) {
-            task.fiber.handleError(e);
+          task.fiber.complete();
+          if (!task.fiber.isCompleted) {
+            return true;
           }
         }
         task.callback();

tests/component/component.test.ts

@@ -2165,28 +2165,28 @@ describe("other directives with t-component", () => {
         grandChild = this;
       }
       _onEv() {
-        steps.push('GrandChild');
+        steps.push("GrandChild");
       }
     }
     class Child extends Component<any, any> {
       static template = xml`<GrandChild t-on-ev="_onEv"/>`;
       static components = { GrandChild };
       _onEv() {
-        steps.push('Child');
+        steps.push("Child");
       }
     }
     class Parent extends Component<any, any> {
       static template = xml`<Child t-on-ev="_onEv"/>`;
       static components = { Child };
       _onEv() {
-        steps.push('Parent');
+        steps.push("Parent");
       }
     }
     const parent = new Parent();
     await parent.mount(fixture);
 
     grandChild.trigger("ev");
-    expect(steps).toEqual(['GrandChild', 'Child', 'Parent']);
+    expect(steps).toEqual(["GrandChild", "Child", "Parent"]);
   });
 
   test("t-if works with t-component", async () => {
@@ -4992,41 +4992,35 @@ describe("component error handling (catchError)", () => {
   test.skip("can catch an error in the mounted call", async () => {
     // we do not catch error in mounted anymore
     console.error = jest.fn();
-    env.qweb.addTemplates(`
-      <templates>
-        <div t-name="ErrorBoundary">
-            <t t-if="state.error">Error handled</t>
-            <t t-else="1"><t t-slot="default" /></t>
-        </div>
-        <div t-name="ErrorComponent">Some text</div>
-        <div t-name="App">
-            <ErrorBoundary><ErrorComponent /></ErrorBoundary>
-        </div>
-      </templates>`);
-    class ErrorComponent extends Widget {
+
+    class ErrorComponent extends Component<any,any> {
+      static template = xml`<div>Some text</div>`;
       mounted() {
         throw new Error("NOOOOO");
       }
     }
-    class ErrorBoundary extends Widget {
+    class ErrorBoundary extends Component<any,any> {
+      static template = xml`
+        <div>
+          <t t-if="state.error">Error handled</t>
+          <t t-else="1"><t t-slot="default" /></t>
+        </div>`;
       state = useState({ error: false });
 
       catchError() {
         this.state.error = true;
       }
     }
-    class App extends Widget {
+    class App extends Component<any,any> {
+      static template = xml`<div><ErrorBoundary><ErrorComponent /></ErrorBoundary></div>`;
       static components = { ErrorBoundary, ErrorComponent };
     }
     const app = new App();
     await app.mount(fixture);
-    await nextTick();
-    await nextTick();
-    await nextTick();
     expect(fixture.innerHTML).toBe("<div><div>Error handled</div></div>");
   });
 
-  test.skip("can catch an error in the willPatch call", async () => {
+  test("can catch an error in the willPatch call", async () => {
     // we do not catch error in willPatch anymore
     const consoleError = console.error;
     console.error = jest.fn();
@@ -5054,18 +5048,16 @@ describe("component error handling (catchError)", () => {
             <span><t t-esc="state.message"/></span>
           <ErrorBoundary><ErrorComponent message="state.message" /></ErrorBoundary>
         </div>`;
-      state = useState({ message: "abc" });
+      state = { message: "abc" };
       static components = { ErrorBoundary, ErrorComponent };
     }
     const app = new App();
     await app.mount(fixture);
     expect(fixture.innerHTML).toBe("<div><span>abc</span><div><div>abc</div></div></div>");
     app.state.message = "def";
-    await nextTick();
-    await nextTick();
-    await nextTick();
+    await app.render();
     expect(fixture.innerHTML).toBe("<div><span>def</span><div>Error handled</div></div>");
-    expect(console.error).toHaveBeenCalledTimes(1);
+    expect(console.error).toHaveBeenCalledTimes(0);
     console.error = consoleError;
   });
 

tests/doc_link_checker.test.ts

@@ -85,7 +85,7 @@ function getFiles(path: string[] = []): FileData[] {
   return Array.prototype.concat(...files);
 }
 
-const LOCAL_FILES = ["LICENSE"];
+const LOCAL_FILES = ["LICENSE", "tools/debug.js"];
 export function isLinkValid(link: MarkDownLink, current: FileData, files: FileData[]): boolean {
   if (link.link.startsWith("http")) {
     // no check on external links

tools/debug.js

@@ -0,0 +1,137 @@
+/**
+ * Debug Script
+ *
+ * This code is intended to be evaluated in an environment where owl is available,
+ * to log lot of helpful information on how Owl components behave.
+ */
+
+let debugSetup = {
+  // componentBlackList: /App/,  // regexp
+  // componentWhiteList: /SomeComponent/, // regexp
+  // methodBlackList: ["mounted"], // list of method names
+  // methodWhiteList: ["willStart"], // list of method names
+  logScheduler: true, // display/mute scheduler logs
+  logStore: true // display/mute store logs
+};
+{
+  let prefix = "[OWL_DEBUG]";
+  let current;
+  Object.defineProperty(owl.Component, "current", {
+    get() {
+      return current;
+    },
+    set(comp) {
+      current = comp;
+      const name = comp.constructor.name;
+      if (debugSetup.componentBlackList && debugSetup.componentBlackList.test(name)) {
+        return;
+      }
+      if (debugSetup.componentWhiteList && !debugSetup.componentWhiteList.test(name)) {
+        return;
+      }
+      let __owl__;
+      Object.defineProperty(current, "__owl__", {
+        get() {
+          return __owl__;
+        },
+        set(val) {
+          __owl__ = val;
+          debugComponent(comp, name, __owl__.id);
+        }
+      });
+    }
+  });
+
+  function toStr(obj) {
+    let str = JSON.stringify(obj || {});
+    if (str.length > 200) {
+      str = str.slice(0, 200) + "...";
+    }
+    return str;
+  }
+
+  function debugComponent(component, name, id) {
+    let fullName = `${name}<id=${id}>`;
+    let shouldDebug = method => {
+      if (debugSetup.methodBlackList && debugSetup.methodBlackList.includes(method)) {
+        return false;
+      }
+      if (debugSetup.methodWhiteList && !debugSetup.methodWhiteList.includes(method)) {
+        return false;
+      }
+      return true;
+    };
+    if (shouldDebug("constructor")) {
+      console.log(`${prefix} ${fullName} constructor, props=${toStr(component.props)}`);
+    }
+    if (shouldDebug("willStart")) {
+      owl.hooks.onWillStart(() => {
+        console.log(`${prefix} ${fullName} willStart`);
+      });
+    }
+    if (shouldDebug("mounted")) {
+      owl.hooks.onMounted(() => {
+        console.log(`${prefix} ${fullName} mounted`);
+      });
+    }
+    if (shouldDebug("willUpdateProps")) {
+      owl.hooks.onWillUpdateProps(nextProps => {
+        console.log(`${prefix} ${fullName} willUpdateProps, nextprops=${toStr(nextProps)}`);
+      });
+    }
+    if (shouldDebug("willPatch")) {
+      owl.hooks.onWillPatch(() => {
+        console.log(`${prefix} ${fullName} willPatch`);
+      });
+    }
+    if (shouldDebug("patched")) {
+      owl.hooks.onPatched(() => {
+        console.log(`${prefix} ${fullName} patched`);
+      });
+    }
+    if (shouldDebug("willUnmount")) {
+      owl.hooks.onWillUnmount(() => {
+        console.log(`${prefix} ${fullName} willUnmount`);
+      });
+    }
+    const __render = component.__render.bind(component);
+    component.__render = function(...args) {
+      console.log(`${prefix} ${fullName} rendering template`);
+      __render(...args);
+    };
+    const render = component.render.bind(component);
+    component.render = function(...args) {
+      console.log(`${prefix} ${fullName} render`);
+      return render(...args);
+    };
+    const mount = component.mount.bind(component);
+    component.mount = function(...args) {
+      console.log(`${prefix} ${fullName} mount`);
+      return mount(...args);
+    };
+  }
+
+  if (debugSetup.logScheduler) {
+    let isRunning;
+    Object.defineProperty(owl.Component.scheduler, "isRunning", {
+      get() {
+        return isRunning;
+      },
+      set(val) {
+        if (val) {
+          console.log(`${prefix} scheduler: start running tasks queue`);
+        } else {
+          console.log(`${prefix} scheduler: stop running tasks queue`);
+        }
+        isRunning = val;
+      }
+    });
+  }
+  if (debugSetup.logStore) {
+    let dispatch = owl.Store.prototype.dispatch;
+    owl.Store.prototype.dispatch = function(action, ...payload) {
+      console.log(`${prefix} store: action '${action}' dispatched. Payload: '${toStr(payload)}'`);
+      return dispatch.call(this, action, ...payload);
+    };
+  }
+}