diff --git a/packages/interactivity-router/README.md b/packages/interactivity-router/README.md
index 94b88e80886c9..efb52e59be2b5 100644
--- a/packages/interactivity-router/README.md
+++ b/packages/interactivity-router/README.md
@@ -1,21 +1,32 @@
-# Interactivity Router
+# `@wordpress/interactivity-router`
-> **Note**
-> This package is a extension of the API shared at [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/). As part of an [Open Source project](https://developer.wordpress.org/block-editor/getting-started/faq/#the-gutenberg-project) we encourage participation in helping shape this API and the [discussions in GitHub](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) is the best place to engage.
+The package `@wordpress/interactivity-router` enables loading content from other pages without a full page reload. Currently, the only supported mode is "region-based". Full "client-side navigation" is still in experimental phase.
-This package defines an Interactivity API store with the `core/router` namespace, exposing state and actions like `navigate` and `prefetch` to handle client-side navigations.
+The package defines an Interactivity API store with the `core/router` namespace, exposing state and 2 actions: `navigate` and `prefetch` to handle client-side navigation.
+
+The `@wordpress/interactivity-router` package was [introduced in WordPress Core in v6.5](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/). This means this package is already bundled in Core in any version of WordPress higher than v6.5.
+
+
## Usage
-The package is intended to be imported dynamically in the `view.js` files of interactive blocks.
+The package is intended to be imported dynamically in the `view.js` files of interactive blocks. This is done in in order to reduce the JS bundle size on the initial page load.
```js
+/* view.js */
+
import { store } from '@wordpress/interactivity';
-store( 'myblock', {
+// This is how you would typically use the navigate() action in your block.
+store( 'my-namespace/myblock', {
actions: {
- *navigate( e ) {
+ *goToPage( e ) {
e.preventDefault();
+
+ // We import the package dynamically to reduce the initial JS bundle size.
+ // Async actions are defined as generators so the import() must be called with `yield`.
const { actions } = yield import(
'@wordpress/interactivity-router'
);
@@ -25,52 +36,116 @@ store( 'myblock', {
} );
```
-## Frequently Asked Questions
+Now, you can call `actions.navigate()` in your block's `view.js` file to navigate to a different page or e.g. pass it to a `data-wp-on--click` attribute.
+
+When loaded, this package [adds the following state and actions](https://github.com/WordPress/gutenberg/blob/ed7d78652526270b63976d7a970dba46a2bfcbb0/packages/interactivity-router/src/index.ts#L212) to the `core/router` store:
+
+```js
+const { state, actions } = store( 'core/router', {
+ state: {
+ url: window.location.href,
+ navigation: {
+ hasStarted: false,
+ hasFinished: false,
+ texts: {
+ loading: '',
+ loaded: '',
+ },
+ message: '',
+ },
+ },
+ actions: {
+ *navigate(href, options) {...},
+ prefetch(url, options) {...},
+ }
+})
+```
+
+
+
+### Directives
+
+#### `data-wp-router-region`
+
+It defines a region that is updated on navigation. It requires a unique ID as the value and can only be used in root interactive elements, i.e., elements with `data-wp-interactive` that are not nested inside other elements with `data-wp-interactive`.
+
+Example:
+
+```html
+
+```
+
+### Actions
+
+#### `navigate`
+
+Navigates to the specified page.
-At this point, some of the questions you have about the Interactivity API may be:
+This function normalizes the passed `href`, fetches the page HTML if needed, and updates any interactive regions whose contents have changed in the new page. It also creates a new entry in the browser session history.
-### What is this?
+**Params**
-This is the base of a new standard to create interactive blocks. Read [the proposal](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) to learn more about this.
+```js
+navigate( href: string, options: NavigateOptions = {} )
+```
-### Can I use it?
+- `href`: The page `href`.
+- `options`: Options object.
+ - `force`: If `true`, it forces re-fetching the URL. `navigate()` always caches the page, so if the page has been navigated to before, it will be used. Default is `false`.
+ - `html`: HTML string to be used instead of fetching the requested URL.
+ - `replace`: If `true`, it replaces the current entry in the browser session history. Default is `false`.
+ - `timeout`: Time until the navigation is aborted, in milliseconds. Default is `10000`.
+ - `loadingAnimation`: Whether an animation should be shown while navigating. Default to `true`.
+ - `screenReaderAnnouncement`: Whether a message for screen readers should be announced while navigating. Default to `true`.
-You can test it, but it's still very experimental.
+#### `prefetch`
-### How do I get started?
+Prefetches the page for the passed URL. The page is cached and can be used for navigation.
-The best place to start with the Interactivity API is this [**Getting started guide**](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/1-getting-started.md). There you'll will find a very quick start guide and the current requirements of the Interactivity API.
+The function normalizes the URL and stores internally the fetch promise, to avoid triggering a second fetch for an ongoing request.
-### Where can I ask questions?
+**Params**
-The [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions is the best place to ask questions about the Interactivity API.
+```js
+prefetch( url: string, options: PrefetchOptions = {} )
+```
-### Where can I share my feedback about the API?
+- `url`: The page `url`.
+- `options`: Options object.
-The [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions is also the best place to share your feedback about the Interactivity API.
+ - `force`: If `true`, forces fetching the URL again.
+ - `html`: HTML string to be used instead of fetching the requested URL.
+
+### State
+
+`state.url` is a reactive property synchronized with the current URL.
+Properties under `state.navigation` are meant for loading bar animations.
## Installation
Install the module:
```bash
-npm install @wordpress/interactivity --save
+npm install @wordpress/interactivity-router --save
```
-_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
-
-## Docs & Examples
+This step is only required if you use the Interactivity API outside WordPress.
-**[Interactivity API Documentation](https://github.com/WordPress/gutenberg/tree/trunk/packages/interactivity/docs)** is the best place to learn about this proposal. Although it's still in progress, some key pages are already available:
+Within WordPress, the package is already bundled in Core. To ensure it's enqueued, add `@wordpress/interactivity-router` to the dependency array of the script module. This process is often done automatically with tools like [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/).
-- **[Getting Started Guide](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/1-getting-started.md)**: Follow this Getting Started guide to learn how to scaffold a new project and create your first interactive blocks.
-- **[API Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/2-api-reference.md)**: Check this page for technical detailed explanations and examples of the directives and the store.
+Furthermore, this package assumes your code will run in an **ES2015+** environment. If you're using an environment with limited or no support for such language features and APIs, you should include the polyfill shipped in [`@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code.
-Here you have some more resources to learn/read more about the Interactivity API:
+## License
-- **[Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882)**
-- [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/)
-- Developer Hours sessions ([Americas](https://www.youtube.com/watch?v=RXNoyP2ZiS8&t=664s) & [APAC/EMEA](https://www.youtube.com/watch?v=6ghbrhyAcvA))
-- [wpmovies.dev](http://wpmovies.dev/) demo and its [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) repo
+Interactivity API proposal, as part of Gutenberg and the WordPress project is free software, and is released under the terms of the GNU General Public License version 2 or (at your option) any later version. See [LICENSE.md](https://github.com/WordPress/gutenberg/blob/trunk/LICENSE.md) for complete license.
-
+