Master more doc ged

CHANGELOG.md

@@ -53,7 +53,7 @@ All changes are documented here in no particular order.
 
 - finer grained reactivity: owl 2 tracks change per key/component
 - finer grained reactivity: sub components can reobserve state ([doc](doc/reference/reactivity.md))
-- new: `reactive` function: create reactive state (without being linked to a component) ([doc](doc/reference/reactivity.md#reactive))
+- new: `reactive` function: create reactive state (without being linked to a component) ([doc](doc/reference/reactivity.md#proxy))
 - new: `markRaw` function: mark an object or array so that it is ignored by the reactivity system ([doc](doc/reference/reactivity.md#markraw))
 - new: `toRaw` function: given a reactive objet, return the raw (non reactive) underlying object ([doc](doc/reference/reactivity.md#toraw))
 
@@ -308,7 +308,7 @@ prepended in something, maybe a `div`. Remember that you the root component
 can have multiple roots
 
 Documentation:
-- [Fragments](doc/reference/templates.md#fragments)
+- [Fragments](doc/reference/template_syntax.md#fragments)
 - [Mounting a component](doc/reference/app.md#mount-helper)
 
 
@@ -522,7 +522,7 @@ us so we can study this usecase.
 In Owl, a call to `useSubEnv` would define a new environment for the children
 AND the component. It is very useful, but in some cases, one only need to update
 the children component environment. This can now be done with a new hook:
-[`useChildSubEnv`](doc/reference/hooks.md#usesubenv-and-usechildsubenv)
+[`useChildSubEnv`](doc/reference/hooks.md)
 
 ### 28. `env` is now frozen
 
@@ -593,7 +593,7 @@ So, the following template works for components:
   hello
 ```
 
-Documentation: [Fragments](doc/reference/templates.md#fragments)
+Documentation: [Fragments](doc/reference/template_syntax.md#fragments)
 
 ### 32. `renderToString` on QWeb has been removed
 
@@ -731,7 +731,7 @@ Otherwise, it will be escaped (just like `t-esc`).
 Migration: replace all `t-raw` uses by `t-out`, and uses the `markup` function
 to mark all the js values.
 
-Documentation: [Outputting data](doc/reference/templates.md#outputting-data)
+Documentation: [Outputting data](doc/reference/template_syntax.md#outputting-data)
 
 ## 39. `browser` object has been removed
 

README.md

@@ -81,51 +81,41 @@ 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.
 
-## Design Principles
+## Documentation
 
-Owl is built on principles that make it powerful yet approachable:
-
-**Explicit over Implicit**
-
-Reactiveness is explicit — you read signals by calling them (`this.count()`),
-making dependencies visible and bugs easier to trace. No hidden magic.
-
-**Composable Architecture**
-
-Plugins provide a structured way to share state and services across components.
-They compose naturally and support full type inference.
-
-**Scales with You**
-
-Start simple with inline templates and signals. Grow into a large codebase
-with external templates, registries, and plugins. Owl powers Odoo's
-multi-million-line codebase — it's proven at scale.
-
-**Developer Experience**
-
-First-class TypeScript support, comprehensive error messages in dev mode,
-and a browser devtools extension for debugging.
-
-## Resources
+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).
 
 ### Getting Started
 
 - **[Playground](https://odoo.github.io/owl/playground)** — Interactive examples and live coding
-- **[Owl 3.x Release Notes](release_notes.md)** — Complete guide to all changes
 - [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 Documentation
-
-- [Overview](doc/readme.md)
-- [App](doc/reference/app.md) | [Component](doc/reference/component.md)
-- [Reactivity](doc/reference/reactivity.md) | [Hooks](doc/reference/hooks.md)
-- [Templates](doc/reference/templates.md) | [Props](doc/reference/props.md)
-- [Slots](doc/reference/slots.md)
-
-### Understanding Owl
-
+### Reference
+
+- [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)

doc/miscellaneous/comparison.md

@@ -78,7 +78,7 @@ additional tools, we made a lot of effort to make the most of the web platform.
 
 For example, Owl uses the standard `xml` parser that comes with every browser.
 Because of that, Owl did not have to write its own template parser. Another
-example is the [`xml`](../reference/templates.md#inline-templates) tag helper function, which makes use of
+example is the [`xml`](../reference/template_syntax.md#inline-templates) tag helper function, which makes use of
 native template literals to allow in a natural way to write `xml` templates
 directly in the javascript code. This can be easily integrated with editor
 plugins to have autocompletion inside the template.
@@ -126,7 +126,7 @@ structured than a template language. Note that the tooling is quite impressive:
 there is a syntax highlighter for jsx here on github!
 
 By comparison, here is the equivalent Owl component, written with the
-[`xml`](../reference/templates.md#inline-templates) tag helper:
+[`xml`](../reference/template_syntax.md#inline-templates) tag helper:
 
 ```js
 class Clock extends Component {
@@ -142,13 +142,12 @@ class Clock extends Component {
 ## Asynchronous Rendering
 
 This is actually a big difference between OWL and React/Vue: components in OWL
-are totally asynchronous. They have two asynchronous hooks in their lifecycle:
+are totally asynchronous. They have an asynchronous hook in their lifecycle:
 
 - `willStart` (before the component starts rendering)
-- `willUpdateProps` (before new props are set)
 
-Both these methods can be implemented and return a promise. The rendering will
-then wait for these promises to be completed before patching the DOM. This is
+This method can be implemented and return a promise. The rendering will
+then wait for the promise to be completed before patching the DOM. This is
 useful for some use cases: for example, a component may want to fetch an external
 library (a calendar component may need a specialized calendar rendering library),
 in its willStart hook.

doc/miscellaneous/design_principles.md

@@ -0,0 +1,24 @@
+# Design Principles
+
+Owl is built on principles that make it powerful yet approachable:
+
+**Explicit over Implicit**
+
+Reactiveness is explicit — you read signals by calling them (`this.count()`),
+making dependencies visible and bugs easier to trace. No hidden magic.
+
+**Composable Architecture**
+
+Plugins provide a structured way to share state and services across components.
+They compose naturally and support full type inference.
+
+**Scales with You**
+
+Start simple with inline templates and signals. Grow into a large codebase
+with external templates, registries, and plugins. Owl powers Odoo's
+multi-million-line codebase — it's proven at scale.
+
+**Developer Experience**
+
+First-class TypeScript support, comprehensive error messages in dev mode,
+and a browser devtools extension for debugging.

doc/readme.md

@@ -1,49 +1,59 @@
-# 🦉 Owl overview 🦉
+# 🦉 API Reference 🦉
 
-Here is a list of everything exported by the Owl library:
+Here is a list of everything exported by the Owl library.
 
-Main entities:
+## Core
 
-- [`App`](reference/app.md): represent an Owl application (mainly a root component,a set of templates, and a config)
-- [`Component`](reference/component.md): the main class to define a concrete Owl component
-- [`mount`](reference/app.md#mount-helper): main entry point for most application: mount a component to a target
-- [`xml`](reference/templates.md#inline-templates): helper to define an inline template
+- [`App`](reference/app.md): an Owl application (root components, templates, and config)
+- [`Component`](reference/component.md): base class for Owl components
+- [`mount`](reference/app.md#mount-helper): mount a component to a DOM target
+- [`xml`](reference/template_syntax.md#inline-templates): define an inline template
+- [`props`](reference/props.md): declare and validate component props
+- [`status`](reference/component.md#status-helper): get the status of a component (new, mounted, destroyed)
 
-Reactivity
+## Reactivity
 
-- [`useState`](reference/reactivity.md#usestate): create a reactive object (hook, linked to a specific component)
-- [`reactive`](reference/reactivity.md#reactive): create a reactive object (not linked to any component)
-- [`markRaw`](reference/reactivity.md#markraw): mark an object or array so that it is ignored by the reactivity system
-- [`toRaw`](reference/reactivity.md#toraw): given a reactive objet, return the raw (non reactive) underlying object
+- [`signal`](reference/reactivity.md#signals): create a reactive value
+- [`computed`](reference/reactivity.md#computed-values): create a lazily-evaluated derived value
+- [`proxy`](reference/reactivity.md#proxy): create a reactive proxy for an object
+- [`effect`](reference/reactivity.md#effects): create a side effect that re-runs when dependencies change
+- [`markRaw`](reference/reactivity.md#markraw): mark an object so it is ignored by the reactivity system
+- [`toRaw`](reference/reactivity.md#toraw): given a proxy, return the underlying non-reactive object
+- [`untrack`](reference/reactivity.md#untrack): execute a function without tracking reactive dependencies
 
-Lifecycle hooks:
+## Lifecycle Hooks
 
-- [`onWillStart`](reference/component.md#willstart): hook to define asynchronous code that should be executed before component is rendered
-- [`onMounted`](reference/component.md#mounted): hook to define code that should be executed when component is mounted
-- [`onWillPatch`](reference/component.md#willpatch): hook to define code that should be executed before component is patched
-- [`onWillUpdateProps`](reference/component.md#willupdateprops): hook to define code that should be executed before component is updated
-- [`onPatched`](reference/component.md#patched): hook to define code that should be executed when component is patched
-- [`onWillRender`](reference/component.md#willrender): hook to define code that should be executed before component is rendered
-- [`onRendered`](reference/component.md#rendered): hook to define code that should be executed after component is rendered
-- [`onWillUnmount`](reference/component.md#willunmount): hook to define code that should be executed before component is unmounted
-- [`onWillDestroy`](reference/component.md#willdestroy): hook to define code that should be executed before component is destroyed
-- [`onError`](reference/component.md#onerror): hook to define a Owl error handler
+- [`onWillStart`](reference/component.md#willstart): async, before first rendering
+- [`onMounted`](reference/component.md#mounted): after component is rendered and added to the DOM
+- [`onWillPatch`](reference/component.md#willpatch): before the DOM is patched
+- [`onPatched`](reference/component.md#patched): after the DOM is patched
+- [`onWillUnmount`](reference/component.md#willunmount): before removing component from DOM
+- [`onWillDestroy`](reference/component.md#willdestroy): before component is destroyed
+- [`onError`](reference/component.md#onerror): catch and handle errors
 
-Other hooks:
+## Other Hooks
 
-- [`useComponent`](reference/hooks.md#usecomponent): return a reference to the current component (useful to create derived hooks)
-- [`useEffect`](reference/hooks.md#useeffect): define an effect with its dependencies
-- [`useEnv`](reference/hooks.md#useenv): return a reference to the current env
-- [`useListener`](reference/hooks.md#uselistener): add a listener outside of a component DOM
-- [`useRef`](reference/hooks.md#useref): get an object representing a reference (`t-ref`)
-- [`useChildSubEnv`](reference/hooks.md#usesubenv-and-usechildsubenv): extend the current env with additional information (for child components)
-- [`useSubEnv`](reference/hooks.md#usesubenv-and-usechildsubenv): extend the current env with additional information (for current component and child components)
+- [`useEffect`](reference/hooks.md#useeffect): create a reactive effect, cleaned up on destroy
+- [`useListener`](reference/hooks.md#uselistener): add a listener to a target, removed on destroy
+- [`useApp`](reference/hooks.md#useapp): get the current App instance
 
-Utility/helpers:
+## Plugins
+
+- [`Plugin`](reference/plugins.md): base class for plugins
+- [`plugin`](reference/plugins.md): import a plugin dependency
+- [`providePlugins`](reference/plugins.md): make plugins available to a component subtree
+
+## Type Validation
+
+- [`types`](reference/types_validation.md#validators): built-in type validators
+- [`validateType`](reference/types_validation.md#validatetype): check a value against a type validator
+- [`assertType`](reference/types_validation.md#asserttype): like validateType, but throws on failure
+
+## Utilities
 
 - [`EventBus`](reference/utils.md#eventbus): a simple event bus
-- [`markup`](reference/templates.md#outputting-data): utility function to define strings that represent html (should not be escaped)
-- [`status`](reference/component.md#status-helper): utility function to get the status of a component (new, mounted or destroyed)
-- [`validate`](reference/utils.md#validate): validates if an object satisfies a specified schema
-- [`whenReady`](reference/utils.md#whenready): utility function to execute code when DOM is ready
-- [`batched`](reference/utils.md#batched): utility function to batch function calls
+- [`markup`](reference/template_syntax.md#outputting-data): mark a string as safe HTML (not escaped by `t-out`)
+- [`batched`](reference/utils.md#batched): batch function calls into a single microtask execution
+- [`whenReady`](reference/utils.md#whenready): execute code when the DOM is ready
+- [`Registry`](reference/resources_and_registries.md#registry): ordered key-value collection with reactivity
+- [`Resource`](reference/resources_and_registries.md#resource): ordered set collection with reactivity

doc/reference/app.md

@@ -66,7 +66,7 @@ The `config` object is an object with some of the following keys:
 - **`warnIfNoStaticProps (boolean, default=false)`**: if true, Owl will log a warning
   whenever it encounters a component that does not provide a [static props description](props.md#props-validation).
 - **`customDirectives (object)`**: if given, the corresponding function on the object will be called
-  on the template custom directives: `t-custom-*` (see [Custom Directives](templates.md#custom-directives)).
+  on the template custom directives: `t-custom-*` (see [Custom Directives](template_syntax.md#custom-directives)).
 - **`globalValues (object)`**: Global object of elements available at compilations.
 
 ## `mount` helper
@@ -149,7 +149,7 @@ const { mount } = owl;
 Dev mode activates some additional checks and developer amenities:
 
 - [Props validation](./props.md#props-validation) is performed
-- [t-foreach](./templates.md#loops) loops check for key unicity
+- [t-foreach](./template_syntax.md#loops) loops check for key unicity
 - Lifecycle hooks are wrapped to report their errors in a more developer-friendly way
-- onWillStart and onWillUpdateProps will emit a warning in the console when they
-  take longer than 3 seconds in an effort to ease debugging the presence of deadlocks
+- onWillStart will emit a warning in the console when it takes longer than 3
+  seconds in an effort to ease debugging the presence of deadlocks