@odoo/owl 3.0.0-alpha.2 → 3.0.0-alpha.21

package/README.md

@@ -1,149 +1,139 @@
-<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</a> 🦉</h1>
 
- [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
+<p align="center">
+  <strong>A modern, lightweight UI framework for applications that scale</strong>
+</p>
+
+[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
 [![npm version](https://badge.fury.io/js/@odoo%2Fowl.svg)](https://badge.fury.io/js/@odoo%2Fowl)
 [![Downloads](https://img.shields.io/npm/dm/@odoo%2Fowl.svg)](https://www.npmjs.com/package/@odoo/owl)
 
-_Class based components with hooks, reactive state and concurrent mode_
+---
 
-**Try it online!** you can experiment with the Owl framework in an online [playground](https://odoo.github.io/owl/playground).
+> **Owl 3.0.0 Alpha:** This is an alpha release. The API and features are subject to change without notice.
 
-## Project Overview
+---
 
-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:
+## Try it now
 
-- a declarative component system,
-- a fine grained reactivity system similar to Vue,
-- hooks
-- fragments
-- asynchronous rendering
+The fastest way to discover Owl is the **[online playground](https://odoo.github.io/owl/playground)**.
+It features interactive examples, a live editor, and showcases all major features:
+reactivity, components, plugins, and more. It also includes **guided tutorials**
+and is the recommended way to learn about Owl.
 
-Owl components are defined with ES6 classes and xml templates, uses an
-underlying virtual DOM, integrates beautifully with hooks, and the rendering is
-asynchronous.
+## What is Owl?
 
-Quick links:
+Owl is a modern UI framework (~20kb gzipped, zero dependencies) written in TypeScript,
+built by [Odoo](https://www.odoo.com/). It powers Odoo's web client, one of the largest
+open-source business applications, but is equally suited for small projects and prototypes.
 
-- [documentation](#documentation),
-- [changelog](CHANGELOG.md) (from Owl 1.x to 2.x),
-- [playground](https://odoo.github.io/owl/playground)
+Key features:
 
-## Example
+- **Signal-based reactivity** — Explicit, composable, and debuggable state management
+- **Plugin system** — Type-safe, composable sharing of state and services
+- **Class-based components** — Familiar OOP patterns with ES6 classes
+- **Declarative templates** — XML templates with a clean syntax
+- **Async rendering** — Concurrent mode for smooth user experiences
 
-Here is a short example to illustrate interactive components:
+## Quick Example
 
 ```javascript
-const { Component, useState, mount, xml } = owl;
+import { Component, signal, computed, mount, xml } from "@odoo/owl";
 
-class Counter extends Component {
+class TodoList extends Component {
   static template = xml`
-    <button t-on-click="() => state.value = state.value + props.increment">
-      Click Me! [<t t-esc="state.value"/>]
-    </button>`;
-
-  state = useState({ value: 0 });
+    <input placeholder="Add todo..." t-on-keydown="this.onKeydown"/>
+    <ul>
+      <t t-foreach="this.todos()" t-as="todo" t-key="todo.id">
+        <li t-att-class="{ done: todo.done }">
+          <input type="checkbox" t-model="todo.done"/>
+          <t t-out="todo.text"/>
+        </li>
+      </t>
+    </ul>
+    <p t-if="this.remaining() > 0">
+      <t t-out="this.remaining()"/> item(s) remaining
+    </p>`;
+
+  todos = signal.Array([
+    { id: 1, text: "Learn Owl", done: false },
+    { id: 2, text: "Build something", done: false },
+  ]);
+
+  remaining = computed(() => this.todos().filter((t) => !t.done).length);
+
+  onKeydown(ev) {
+    if (ev.key === "Enter" && ev.target.value) {
+      this.todos.push({
+        id: Date.now(),
+        text: ev.target.value,
+        done: false,
+      });
+      ev.target.value = "";
+    }
+  }
 }
 
-class Root extends Component {
-  static template = xml`
-    <span>Hello Owl</span>
-    <Counter increment="2"/>`;
-
-  static components = { Counter };
-}
-
-mount(Root, document.body);
+mount(TodoList, 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/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.
+This example demonstrates Owl's reactivity: `todos` is a signal, `remaining`
+is a computed value that updates automatically, and the UI reacts to changes
+without manual subscription management.
 
 ## Documentation
 
-### Learning Owl
+The documentation below is for **Owl 3**. For the Owl 2 documentation, see the
+[owl-2.x branch](https://github.com/odoo/owl/tree/owl-2.x).
 
-Are you new to Owl? This is the place to start!
+### Getting Started
 
-- [Tutorial: create a TodoList application](doc/learning/tutorial_todoapp.md)
-- [How to start an Owl project](doc/learning/quick_start.md)
-- [How to test Components](doc/learning/how_to_test.md)
+- **[Playground](https://odoo.github.io/owl/playground)** — Interactive examples and live coding
+- [Tutorial: Getting Started](https://odoo.github.io/owl/playground#getting_started) — Learn Owl fundamentals step by step
+- [Tutorial: Todo List](https://odoo.github.io/owl/playground#todo_list) — Build a full TodoMVC app
+- [Tutorial: Hibou OS](https://odoo.github.io/owl/playground#hibou_os) — Build a desktop-like interface
 
 ### 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)
-- [Dev mode](doc/reference/app.md#dev-mode)
-- [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)
-- [Precompiling templates](doc/reference/precompiling_templates.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)
+- [API Reference](doc/readme.md) — A complete list of everything exported by the Owl library
+- [App](doc/reference/app.md) — Configure and mount an Owl application to the DOM
+- [Component](doc/reference/component.md) — Define components with lifecycle methods and static properties
+- [Error Handling](doc/reference/error_handling.md) — Catch and recover from errors in components
+- [Event Handling](doc/reference/event_handling.md) — Handle DOM events with t-on directives
+- [Form Bindings](doc/reference/form_bindings.md) — Bind form inputs to reactive state with t-model
+- [Hooks](doc/reference/hooks.md) — Use lifecycle hooks and other built-in hooks in components
+- [Plugins](doc/reference/plugins.md) — Share state and services across components with type-safe plugins
+- [Props](doc/reference/props.md) — Pass data to child components with validation and defaults
+- [Reactivity](doc/reference/reactivity.md) — Manage state with signals, computed values, and reactive objects
+- [Refs](doc/reference/refs.md) — Access DOM elements from components with t-ref
+- [Resources and Registries](doc/reference/resources_and_registries.md) — Ordered reactive collections for shared data
+- [Slots](doc/reference/slots.md) — Compose components with named and dynamic slot content
+- [Template Syntax](doc/reference/template_syntax.md) — Write XML templates with QWeb directives
+- [Translations](doc/reference/translations.md) — Translate templates and dynamic strings
+- [Types Validation](doc/reference/types_validation.md) — Validate data structures at runtime with a declarative schema
+
+### Misc
+
+- [Owl 3.x Release Notes](release_notes.md) — Complete guide to all changes in Owl 3
+- [Design Principles](doc/miscellaneous/design_principles.md)
+- [Why we built Owl](doc/miscellaneous/why_owl.md)
+- [Architecture Notes](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)
-- [Notes on compiled templates](doc/miscellaneous/compiled_template.md)
-- [Owl devtools extension](doc/tools/devtools.md)
 
-## Installing Owl
+## Installation
 
-Owl is available on `npm` and can be installed with the following command:
-
-```
+```bash
 npm install @odoo/owl
 ```
-If you want to use a simple `<script>` tag, the last release can be downloaded here:
-
-- [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.
+Or download directly: [latest release](https://github.com/odoo/owl/releases/latest)
 
-### 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.
+## Devtools
 
-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.
+The Owl devtools extension helps debug your applications with component tree
+inspection, state visualization, and performance profiling. Download it from
+the [releases page](https://github.com/odoo/owl/releases/latest).
 
+## License
 
+Owl is released under the [LGPL v3](https://www.gnu.org/licenses/lgpl-3.0) license.