[IMP] hooks/Context: add Context and useContext

Closes #310

doc/context.md

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

doc/hooks.md

@@ -12,6 +12,7 @@
   - [`onWillUnmount`](#onwillunmount)
   - [`onWillPatch`](#onwillpatch)
   - [`onPatched`](#onpatched)
+  - [`useContext`](#usecontext)
   - [`useRef`](#useref)
   - [`useSubEnv`](#usesubenv)
 
@@ -182,7 +183,6 @@ is mounted (see example on top of this page).
 abstractions. `onWillUnmount` registers a callback, which will be called when the component
 is unmounted (see example on top of this page).
 
-
 ### `onWillPatch`
 
 `onWillPatch` is not an user hook, but is a building block designed to help make useful
@@ -195,6 +195,10 @@ before the component patched.
 abstractions. `onPatched` registers a callback, which will be called just
 after the component patched.
 
+### `useContext`
+
+See [`useContext`](context.md#usecontext) for reference documentation.
+
 ### `useRef`
 
 The `useRef` hook is useful when we need a way to interact with some inside part
@@ -251,7 +255,7 @@ If this is not the case, accessing `el` or `comp` on it will return `null`.
 ### `useSubEnv`
 
 The environment is sometimes useful to share some common information between
-all components.  But sometimes, we want to *scope* that knowledge to a subtree.
+all components. But sometimes, we want to _scope_ that knowledge to a subtree.
 
 For example, if we have a form view component, maybe we would like to make some
 `model` object available to all sub component, but not to the whole application.
@@ -271,5 +275,5 @@ class FormComponent extends Component {
 
 The `useSubEnv` takes one argument: an object which contains some key/value that
 will be added to the parent environment. Note that it will extend, not replace
-the parent environment.  And of course, the parent environment will not be
-affected.
+the parent environment. And of course, the parent environment will not be
+affected.

doc/readme.md

@@ -8,6 +8,7 @@ build applications. Here is a complete representation of its content:
 ```
 owl
     Component
+    Context
     QWeb
     useState
     core
@@ -18,6 +19,7 @@ owl
         onWillUnmount
         onWillPatch
         onPatched
+        useContext
         useState
         useRef
         useSubEnv
@@ -44,6 +46,7 @@ Note that for convenience, the `useState` hook is also exported at the root of t
 
 - [Animations](animations.md)
 - [Component](component.md)
+- [Context](context.md)
 - [Event Bus](event_bus.md)
 - [Hooks](hooks.md)
 - [Observer](observer.md)