@odoo/owl 3.0.0-alpha.20 → 3.0.0-alpha.22

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.

package/dist/compile_templates.mjs

@@ -229,11 +229,18 @@ const isRightSeparator = (token) => token && (token.type === "RIGHT_BRACE" || to
  * the arrow operator, then we add the current (or some previous tokens) token to
  * the list of variables so it does not get replaced by a lookup in the context
  */
-function compileExprToArray(expr) {
+// Leading spaces are trimmed during tokenization, so they need to be added back for some values
+const paddedValues = new Map([["in ", " in "]]);
+/**
+ * Processes a javascript expression: compiles variable lookups and detects
+ * top-level arrow functions with their free variables, all in a single pass.
+ */
+function processExpr(expr) {
     const localVars = new Set();
     const tokens = tokenize(expr);
     let i = 0;
     let stack = []; // to track last opening (, [ or {
+    let topLevelArrowIndex = -1;
     while (i < tokens.length) {
         let token = tokens[i];
         let prevToken = tokens[i - 1];
@@ -274,18 +281,21 @@ function compileExprToArray(expr) {
             token.value = token.replace((expr) => compileExpr(expr));
         }
         if (nextToken && nextToken.type === "OPERATOR" && nextToken.value === "=>") {
+            if (stack.length === 0) {
+                topLevelArrowIndex = i + 1;
+            }
             if (token.type === "RIGHT_PAREN") {
                 let j = i - 1;
                 while (j > 0 && tokens[j].type !== "LEFT_PAREN") {
                     if (tokens[j].type === "SYMBOL" && tokens[j].originalValue) {
                         tokens[j].value = tokens[j].originalValue;
-                        localVars.add(tokens[j].value); //] = { id: tokens[j].value, expr: tokens[j].value };
+                        localVars.add(tokens[j].value);
                     }
                     j--;
                 }
             }
             else {
-                localVars.add(token.value); //] = { id: token.value, expr: token.value };
+                localVars.add(token.value);
             }
         }
         if (isVar) {
@@ -306,14 +316,24 @@ function compileExprToArray(expr) {
             token.isLocal = true;
         }
     }
-    return tokens;
+    // Collect free variables from arrow function body
+    let freeVariables = null;
+    if (topLevelArrowIndex !== -1) {
+        freeVariables = [];
+        const seen = new Set();
+        for (let i = topLevelArrowIndex + 1; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t.varName && !t.isLocal && t.varName !== "this" && !seen.has(t.varName)) {
+                seen.add(t.varName);
+                freeVariables.push(t.varName);
+            }
+        }
+    }
+    const compiled = tokens.map((t) => paddedValues.get(t.value) || t.value).join("");
+    return { expr: compiled, freeVariables };
 }
-// Leading spaces are trimmed during tokenization, so they need to be added back for some values
-const paddedValues = new Map([["in ", " in "]]);
 function compileExpr(expr) {
-    return compileExprToArray(expr)
-        .map((t) => paddedValues.get(t.value) || t.value)
-        .join("");
+    return processExpr(expr).expr;
 }
 const INTERP_REGEXP = /\{\{.*?\}\}|\#\{.*?\}/g;
 function replaceDynamicParts(s, replacer) {
@@ -332,8 +352,11 @@ const zero = Symbol("zero");
 const whitespaceRE = /\s+/g;
 // using a non-html document so that <inner/outer>HTML serializes as XML instead
 // of HTML (as we will parse it as xml later)
-const xmlDoc = document.implementation.createDocument(null, null, null);
-const MODS = new Set(["stop", "capture", "prevent", "self", "synthetic"]);
+let xmlDoc;
+if (typeof document !== "undefined") {
+    xmlDoc = document.implementation.createDocument(null, null, null);
+}
+const MODS = new Set(["stop", "capture", "prevent", "self", "synthetic", "passive"]);
 let nextDataIds = {};
 function generateId(prefix = "") {
     nextDataIds[prefix] = (nextDataIds[prefix] || 0) + 1;
@@ -693,8 +716,6 @@ class CodeGenerator {
                 return this.compileTTranslation(ast, ctx);
             case 16 /* ASTType.TTranslationContext */:
                 return this.compileTTranslationContext(ast, ctx);
-            case 17 /* ASTType.TPortal */:
-                return this.compileTPortal(ast, ctx);
         }
     }
     compileDebug(ast, ctx) {
@@ -780,7 +801,8 @@ class CodeGenerator {
             hoistedExpr = `(ctx,${bareArrowMatch[1]})=>${rest}`;
         }
         else {
-            hoistedExpr = `(ctx, ev) => (${compiled}).call(ctx['this'], ev)`;
+            this.helpers.add("callHandler");
+            hoistedExpr = `(ctx, ev) => callHandler(${compiled}, ctx, ev)`;
         }
         const id = generateId("hdlr_fn");
         this.staticDefs.push({ id, expr: hoistedExpr });
@@ -858,11 +880,22 @@ class CodeGenerator {
         // t-model
         let tModelSelectedExpr;
         if (ast.model) {
-            const { hasDynamicChildren, expr, eventType, shouldNumberize, shouldTrim, targetAttr, specialInitTargetAttr, } = ast.model;
-            const expression = compileExpr(expr);
-            const exprId = generateId("expr");
-            this.helpers.add("modelExpr");
-            this.define(exprId, `modelExpr(${expression})`);
+            const { hasDynamicChildren, expr, eventType, shouldNumberize, shouldTrim, targetAttr, specialInitTargetAttr, isProxy, } = ast.model;
+            let readExpr;
+            let writeExpr;
+            if (isProxy) {
+                const expression = compileExpr(expr);
+                readExpr = expression;
+                writeExpr = (value) => `${expression} = ${value}`;
+            }
+            else {
+                const exprId = generateId("expr");
+                const expression = compileExpr(expr);
+                this.helpers.add("modelExpr");
+                this.define(exprId, `modelExpr(${expression})`);
+                readExpr = `${exprId}()`;
+                writeExpr = (value) => `${exprId}.set(${value})`;
+            }
             let idx;
             if (specialInitTargetAttr) {
                 let targetExpr = targetAttr in attrs && `'${attrs[targetAttr]}'`;
@@ -873,23 +906,23 @@ class CodeGenerator {
                         targetExpr = compileExpr(dynamicTgExpr);
                     }
                 }
-                idx = block.insertData(`${exprId}() === ${targetExpr}`, "prop");
+                idx = block.insertData(`${readExpr} === ${targetExpr}`, "prop");
                 attrs[`block-property-${idx}`] = specialInitTargetAttr;
             }
             else if (hasDynamicChildren) {
                 const bValueId = generateId("bValue");
                 tModelSelectedExpr = `${bValueId}`;
-                this.define(tModelSelectedExpr, `${exprId}()`);
+                this.define(tModelSelectedExpr, readExpr);
             }
             else {
-                idx = block.insertData(`${exprId}()`, "prop");
+                idx = block.insertData(readExpr, "prop");
                 attrs[`block-property-${idx}`] = targetAttr;
             }
             this.helpers.add("toNumber");
             let valueCode = `ev.target.${targetAttr}`;
             valueCode = shouldTrim ? `${valueCode}.trim()` : valueCode;
             valueCode = shouldNumberize ? `toNumber(${valueCode})` : valueCode;
-            const handler = `[(ctx, ev) => { ${exprId}.set(${valueCode}); }, ctx]`;
+            const handler = `[(ctx, ev) => { ${writeExpr(valueCode)}; }, ctx]`;
             idx = block.insertData(handler, "hdlr");
             attrs[`block-handler-${idx}`] = eventType;
         }
@@ -1182,12 +1215,11 @@ class CodeGenerator {
         if (ast.context) {
             const dynCtxVar = generateId("ctx");
             this.addLine(`const ${dynCtxVar} = ${compileExpr(ast.context)};`);
-            if (ast.attrs) {
-                ctxExpr = `Object.assign({}, ${dynCtxVar}${attrs.length ? ", " + ctxString : ""})`;
+            if (attrs.length) {
+                ctxExpr = `Object.assign({this: ${dynCtxVar}}, ${ctxString})`;
             }
             else {
-                const thisCtx = `{this: ${dynCtxVar}, __owl__: this.__owl__}`;
-                ctxExpr = `Object.assign({}, ${dynCtxVar}, ${thisCtx}${attrs.length ? ", " + ctxString : ""})`;
+                ctxExpr = `{this: ${dynCtxVar}}`;
             }
         }
         else {
@@ -1332,9 +1364,29 @@ class CodeGenerator {
         let { block } = ctx;
         // props
         const hasSlotsProp = "slots" in (ast.props || {});
-        const props = ast.props
-            ? this.formatPropObject(ast.props, ast.propsTranslationCtx, ctx.translationCtx)
-            : [];
+        const props = [];
+        const propList = [];
+        for (let p in ast.props || {}) {
+            let [name, suffix] = p.split(".");
+            if (suffix) {
+                // .alike, .bind, .translate — delegate to formatProp, no propList entry
+                props.push(this.formatProp(p, ast.props[p], ast.propsTranslationCtx, ctx.translationCtx));
+                continue;
+            }
+            const { expr: compiledValue, freeVariables } = processExpr(ast.props[p]);
+            const propName = /^[a-z_]+$/i.test(name) ? name : `'${name}'`;
+            props.push(`${propName}: ${compiledValue || undefined}`);
+            if (freeVariables) {
+                for (const varName of freeVariables) {
+                    const syntheticKey = `\x01${name}.${varName}`;
+                    propList.push(`"${syntheticKey}"`);
+                    props.push(`"${syntheticKey}": ctx['${varName}']`);
+                }
+            }
+            else {
+                propList.push(`"${name}"`);
+            }
+        }
         // slots
         let slotDef = "";
         if (ast.slots) {
@@ -1391,13 +1443,6 @@ class CodeGenerator {
             keyArg = `${ctx.tKeyExpr} + ${keyArg}`;
         }
         let id = generateId("comp");
-        const propList = [];
-        for (let p in ast.props || {}) {
-            let [name, suffix] = p.split(".");
-            if (!suffix) {
-                propList.push(`"${name}"`);
-            }
-        }
         this.helpers.add("createComponent");
         this.staticDefs.push({
             id,
@@ -1502,26 +1547,6 @@ class CodeGenerator {
         }
         return null;
     }
-    compileTPortal(ast, ctx) {
-        this.helpers.add("Portal");
-        let { block } = ctx;
-        const name = this.compileInNewTarget("slot", ast.content, ctx);
-        let id = generateId("comp");
-        this.helpers.add("createComponent");
-        this.staticDefs.push({
-            id,
-            expr: `createComponent(app, null, false, true, false, false)`,
-        });
-        const target = compileExpr(ast.target);
-        const key = this.generateComponentKey();
-        const blockString = `${id}({target: ${target},slots: {'default': {__render: ${name}.bind(this), __ctx: ctx}}}, ${key}, node, ctx, Portal)`;
-        if (block) {
-            this.insertAnchor(block);
-        }
-        block = this.createBlock(block, "multi", ctx);
-        this.insertBlock(blockString, block, { ...ctx, forceNewBlock: false });
-        return block.varName;
-    }
 }
 
 /**
@@ -1593,7 +1618,6 @@ function parseNode(node, ctx) {
         parseTDebugLog(node, ctx) ||
         parseTForEach(node, ctx) ||
         parseTIf(node, ctx) ||
-        parseTPortal(node, ctx) ||
         parseTTranslation(node, ctx) ||
         parseTTranslationContext(node, ctx) ||
         parseTCall(node, ctx) ||
@@ -1740,6 +1764,7 @@ function parseDOMNode(node, ctx) {
             const hasTrimMod = attr.includes(".trim");
             const hasLazyMod = hasTrimMod || attr.includes(".lazy");
             const hasNumberMod = attr.includes(".number");
+            const hasProxyMod = attr.includes(".proxy");
             const eventType = isRadioInput ? "click" : isSelect || hasLazyMod ? "change" : "input";
             model = {
                 expr: value,
@@ -1749,6 +1774,7 @@ function parseDOMNode(node, ctx) {
                 hasDynamicChildren: false,
                 shouldTrim: hasTrimMod,
                 shouldNumberize: hasNumberMod,
+                isProxy: hasProxyMod,
             };
             if (isSelect) {
                 // don't pollute the original ctx
@@ -2220,28 +2246,6 @@ function parseTTranslationContext(node, ctx) {
     return wrapInTTranslationContextAST(result, translationCtx);
 }
 // -----------------------------------------------------------------------------
-// Portal
-// -----------------------------------------------------------------------------
-function parseTPortal(node, ctx) {
-    if (!node.hasAttribute("t-portal")) {
-        return null;
-    }
-    const target = node.getAttribute("t-portal");
-    node.removeAttribute("t-portal");
-    const content = parseNode(node, ctx);
-    if (!content) {
-        return {
-            type: 0 /* ASTType.Text */,
-            value: "",
-        };
-    }
-    return {
-        type: 17 /* ASTType.TPortal */,
-        target,
-        content,
-    };
-}
-// -----------------------------------------------------------------------------
 // helpers
 // -----------------------------------------------------------------------------
 /**