@odoo/owl 1.4.7 → 2.0.0-alpha.1

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">🦉 <a href="https://odoo.github.io/owl/">OWL Framework</a> 🦉</h1>
+<h1 align="center">🦉 <a href="https://odoo.github.io/owl/">Owl Framework</a> 🦉</h1>
 
  [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
 [![npm version](https://badge.fury.io/js/@odoo%2Fowl.svg)](https://badge.fury.io/js/@odoo%2Fowl)
@@ -6,113 +6,110 @@
 
 _Class based components with hooks, reactive state and concurrent mode_
 
+**Try it online!** you can experiment with the Owl framework in an online [playground](https://odoo.github.io/owl/playground).
+
 ## Project Overview
 
-The Odoo Web Library (OWL) is a smallish (~<20kb gzipped) UI framework intended to
-be the basis for the [Odoo](https://www.odoo.com/) Web Client. Owl is a modern
+The Odoo Web Library (Owl) is a smallish (~<20kb gzipped) UI framework built by
+[Odoo](https://www.odoo.com/) for its products. Owl is a modern
 framework, written in Typescript, taking the best ideas from React and Vue in a
 simple and consistent way. Owl's main features are:
 
 - a declarative component system,
-- a reactivity system based on hooks,
-- concurrent mode by default,
-- a store and a frontend router
+- a fine grained reactivity system similar to Vue,
+- hooks
+- fragments
+- asynchronous rendering
 
-Owl components are defined with ES6 classes, they use QWeb templates, an
+Owl components are defined with ES6 classes and xml templates, uses an
 underlying virtual DOM, integrates beautifully with hooks, and the rendering is
 asynchronous.
 
-**Try it online!** An online playground is available at
-[https://odoo.github.io/owl/playground](https://odoo.github.io/owl/playground)
-to let you experiment with the Owl framework. There are some code examples to
-showcase some interesting features.
-
-Owl is currently stable.  Possible future changes are explained in the
-[roadmap](roadmap.md).
-
-## Why Owl?
-
-Why did Odoo decide to make Yet Another Framework?  This is really a question
-that deserves [a long answer](doc/miscellaneous/why_owl.md). But in short, we believe that
-while the current state of the art frameworks are excellent, they are not
-optimized for our use case, and there is still room for something else.
+Quick links:
 
-If you are interested in a comparison with React or Vue, you will
-find some more additional information [here](doc/miscellaneous/comparison.md).
+- [documentation](#documentation),
+- [changelog](CHANGELOG.md) (from Owl 1.x to 2.x),
+- [playground](https://odoo.github.io/owl/playground)
 
 ## Example
 
 Here is a short example to illustrate interactive components:
 
 ```javascript
-const { Component, useState, mount } = owl;
-const { xml } = owl.tags;
+const { Component, useState, mount, xml } = owl;
 
 class Counter extends Component {
   static template = xml`
-    <button t-on-click="state.value++">
+    <button t-on-click="() => state.value = state.value + props.increment">
       Click Me! [<t t-esc="state.value"/>]
     </button>`;
 
   state = useState({ value: 0 });
 }
 
-class App extends Component {
+class Root extends Component {
   static template = xml`
-    <div>
-      <span>Hello Owl</span>
-      <Counter />
-    </div>`;
+    <span>Hello Owl</span>
+    <Counter increment="2"/>`;
 
   static components = { Counter };
 }
 
-mount(App, { target: document.body });
+mount(Root, document.body);
 ```
 
 Note that the counter component is made reactive with the [`useState` hook](doc/reference/hooks.md#usestate).
-Also, all examples here uses the [`xml` helper](doc/reference/tags.md#xml-tag) to define inline templates.
+Also, all examples here uses the [`xml` helper](doc/reference/templates.md#inline-templates) to define inline templates.
 But this is not mandatory, many applications will load templates separately.
 
 More interesting examples can be found on the
 [playground](https://odoo.github.io/owl/playground) application.
 
-## Design Principles
-
-OWL is designed to be used in highly dynamic applications where changing
-requirements are common and code needs to be maintained by large teams.
-
-- **XML based**: templates are based on the XML format, which allows interesting
-  applications. For example, they could be stored in a database and modified
-  dynamically with `xpaths`.
-- **templates compilation in the browser**: 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.
-- **no toolchain required**: 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 `npm`.
-
-Owl is not designed to be fast nor small (even though it is quite good on those
-two topics). It is a no nonsense framework to build applications. There is only
-one way to define components (with classes). There is no black magic. It just
-works.
-
-
 ## Documentation
 
-A complete documentation for Owl can be found here:
+### Learning Owl
 
-- [Main documentation page](doc/readme.md).
+Are you new to Owl? This is the place to start!
 
-Some of the most important pages are:
-
-- [Tutorial: TodoList application](doc/learning/tutorial_todoapp.md)
+- [Tutorial: create a TodoList application](doc/learning/tutorial_todoapp.md)
 - [How to start an Owl project](doc/learning/quick_start.md)
-- [QWeb templating language](doc/reference/qweb_templating_language.md)
+- [How to test Components](doc/learning/how_to_test.md)
+
+### Reference
+
+- [Overview](doc/readme.md)
+- [App](doc/reference/app.md)
 - [Component](doc/reference/component.md)
+- [Component Lifecycle](doc/reference/component.md#lifecycle)
+- [Concurrency Model](doc/reference/concurrency_model.md)
+- [Dynamic sub components](doc/reference/component.md#dynamic-sub-components)
+- [Environment](doc/reference/environment.md)
+- [Error Handling](doc/reference/error_handling.md)
+- [Event Handling](doc/reference/event_handling.md)
+- [Form Input Bindings](doc/reference/input_bindings.md)
+- [Fragments](doc/reference/templates.md#fragments)
 - [Hooks](doc/reference/hooks.md)
-
+- [Loading Templates](doc/reference/app.md#loading-templates)
+- [Mounting a component](doc/reference/app.md#mount-helper)
+- [Portal](doc/reference/portal.md)
+- [Props](doc/reference/props.md)
+- [Props Validation](doc/reference/props.md#props-validation)
+- [Reactivity](doc/reference/reactivity.md)
+- [Rendering SVG](doc/reference/templates.md#rendering-svg)
+- [Refs](doc/reference/refs.md)
+- [Slots](doc/reference/slots.md)
+- [Sub components](doc/reference/component.md#sub-components)
+- [Sub templates](doc/reference/templates.md#sub-templates)
+- [Templates (Qweb)](doc/reference/templates.md)
+- [Translations](doc/reference/translations.md)
+- [Utils](doc/reference/utils.md)
+
+### Other Topics
+
+- [Notes On Owl Architecture](doc/miscellaneous/architecture.md)
+- [Comparison with React/Vue](doc/miscellaneous/comparison.md)
+- [Why did Odoo build Owl?](doc/miscellaneous/why_owl.md)
+- [Changelog (from owl 1.x to 2.x)](CHANGELOG.md)
 
 ## Installing Owl
 
@@ -126,6 +123,3 @@ If you want to use a simple `<script>` tag, the last release can be downloaded h
 
 - [owl-1.4.7](https://github.com/odoo/owl/releases/tag/v1.4.7)
 
-## License
-
-OWL is [LGPL licensed](./LICENSE).