Docs: Interactivity API - "@wordpress/interactivity-router" README needs to be updated to reflect is not experimental anymore

[juanmaguitar]

In the README of @wordpress/interactivity-router we can read things such as

Can I use it? You can test it, but it’s still very experimental.

This README needs to be reviewed and updated to its latest state

[DAreRodz]

We could take this opportunity to document the exposed API in more depth. 😄

This is a sketch of what the content may be:

---

Description

The package exposes a store with namespace core/router. The idea is to import the package dynamically so it is only enqueued when needed. The example in the README file is fine.

Currently, the only supported mode is the region-based, client-side navigation.

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:

<div data-wp-interactive="myblock" data-wp-router-region="main-list">
  <ul>
     <li><a href="/post-1">Post 1</a></li>
     <li><a href="/post-2">Post 2</a></li>
     <li><a href="/post-3">Post 3</a></li>
  </ul>
  <a data-wp-on--click="actions.navigate" href="/page/2">
</div>

Actions

The description and usage can come from the TSDocs:

• navigate( href: string, options: NavigateOptions = {} ) (link)
• prefetch( url: string, options: PrefetchOptions = {} ) (link)

State

I would document state.url, which is a reactive property synchronized with the current URL. The other properties under state.navigation are used for the loading bar animations.