Docs: Interactivity API - Split "API Reference" page in 5 subsections: Directives, Store, Server API, Client APIs and Router

[juanmaguitar]

The current API Reference could be reorganized to distribute its content among specific sections, each dedicated to one of its major topics, as follows:

• Directives
• Store
• Server API
• Client API
• Router (this one is still not part of this page but it would fit great in this new suggested structure)

The suggested final structure would be something like this:

• Directives
  • What are directives?
  • List of directives
  • Values of directives are references to store properties
• Store
  • Elements of the store
    • State
    • Actions
      • Async actions
    • Side Effects
    • Derived state 
      • How to define it but what is this is explained in more detail on Fundamentals of the Interactivity API (Core Concepts) > State, context, and derived state
  • Accessing data in callbacks
  • Setting the store
    • On the client side
    • On the server side
  • Private stores
• Server APIs
  • wp_interactivity_state
  • wp_interactivity_config
  • wp_interactivity_process_directives
  • wp_interactivity_data_wp_context
• Client APIs
  • getContext()
  • getElement()
  • withScope()
• Router
  • Description of a specific Store already created for router purposes

[WPLake]

That would be great. As I understand it, this page will be used for technical documentation, so it shouldn't include things like 'What are directives?' Instead, it should contain a core concepts guide mentioned at the top.

The current example-based approach of the API reference is a great solution, but it lacks the ability to interact with the examples and more intersection examples. So, I propose the following:

1. Add playground links to each example (at least to each significant example)

The ability to interact with examples is an important part of learning and is done well in both React and Vue documentation.

I'm not suggesting the same built-in approach, which is nice but likely not affordable for WP in this case. At least basic "try it in the Playground" links to Fiddle or another setup would work for most examples, even if it requires sacrificing backend features.

2. Add an 'Examples' section to the bottom with intersection examples (based on any common tasks)

Just 2-3 real-world scenarios that show how the iAPI parts are used together to provide reactivity. Providing markup as static definitions without a backend wouldn't be a major issue in my view.

[juanmaguitar]

Thanks @WPLake for your feedback!

That would be great. As I understand it, this page will be used for technical documentation, so it shouldn't include things like 'What are directives?' Instead, it should contain a #62921 mentioned at the top.

Good point! I agree that, with the suggested new structure, the 'What are directives?' should be moved to the core concepts guide section

Add playground links to each example (at least to each significant example)

Yes! The block-development-examples repo mainly provides real examples to support snippets of code in the documentation. The iAPI directives examples could added to block-development-examples repo and referenced in the docs, for example, as it was done at The block wrapper page

[WPLake]

@juanmaguitar Not sure I fully understand the part about the reference. The block wrapper page displays code snippets and links to the full related file in the repository, but it doesn't allow interaction with the code.

Similarly, the examples demo repo contains a 'Live Demo' column and links, but it doesn't allow interaction with the code, which is necessary in this case. So you can see how it looks for editors, but if you want to play with it, you should download it locally and work with npm, etc.

I see two ways to make the interactivity documentation more interactive (😁):

1. Store the snippets in a service like JSFiddle or CodePen and embed them.
2. Store the snippets in the mentioned demo repo and get an interactive element using the prefill-embed feature of CodePen, which allows the creation of playgrounds dynamically based on any code.

The second option looks attractive because you don't need to manage fiddles separately, but it requires injecting a script tag ('https://static.codepen.io/assets/embed/ei.js'), and I'm not sure if wp.org currently supports it. If it isn't feasible, then it might make sense to store the examples as fiddles and embed them via iframe (I assume iframes are supported).

I guess this approach is new to wp.org and may require adoption by the editorial team, but it could be used for many other things to make the documentation more interactive.

[juanmaguitar]

This issue may also be a good place to tackle #61207