Documentation for the Interactivity API - Tracking Issue

[juanmaguitar]

Interactivity API is a proposal for a new standard to create interactive blocks. It's still in an experimental phase and is available with Gutenberg 16.2 or later

This tracking issue compiles all issues related to the documentation of the Interactivity API to keep track of the pending tasks and to ease the coordination of this work.

Interactivity API Docs are currently being created as Markdown files in the /docs folder of the interactivity package . When the Interactivity API is no longer in an experimental phase or is integrated into WordPress Core, the plan is to move this documentation to the Block Editor HandBook

If you are willing to help with the documentation, please add a comment to #51928, and we'll coordinate everyone's efforts.

Tasks

Tasks related to Interactivity API Docs are labelled with [Feature] Interactivity API] & [Type] Developer Documentation]

• Docs: Interactivity API - document wp_interactivity_state in the API reference #63672
• Docs: Interactivity API - Add additional info on Preact's selection over Alpine #63570
• Docs: Interactivity API - Create and "Interactivity API" section under "How to Guides" section and include some initial guides #62922
• Docs: Interactivity API - Create a Core Concepts section for the iAPI #62921
• Docs: Interactivity API - Split "API Reference" page in 5 subsections: Directives, Store, Server API, Client APIs and Router #62920
• Docs: Interactivity API - Create a new page on "Getting Started > Fundamentals of Block Development" to introduce Interactive Blocks using iAPI #62872
• Docs: Interactivity API - "@wordpress/interactivity-router" README needs to be updated to reflect is not experimental anymore #62055
• Docs: Interactivity API - Shape a section in the docs providing a full response to the question "Why it's not possible to just use React?" #60783
• Docs: Interactivity API - Move docs from "Reference Guides > Package Reference > @wordpress/interactivity" to "Reference Guides > Interactivity API Reference" #60781
• Docs: Interactivity API - Region-based client-side navigation router #56638
• Docs: Interactivity API - Rename wp-effect to wp-watch #56641
• Docs: Interactivity API - New store() API #56640
• Create API Reference docs for the Interactivity API #52922
• Add code requirements for using the Interactivity API on any block #52929
• Update README.md of docs folder to include a reference to the API Reference #53384
• Update README.md of interactivity package to include a reference to the docs at docs folder #53386

[juanmaguitar]

The following new issues related to Interactivity API documentation have been created

• Docs: Interactivity API - Region-based client-side navigation router #56638
• Docs: Interactivity API - Slot and Fill directives #56639
• Docs: Interactivity API - Rename wp-effect to wp-watch #56641
• Docs: Interactivity API - New store() API #56640

They're also part of #53740

[luisherranz]

This is the list of APIs that in my opinion would cover the whole spectrum of what the Interactivity API encompasses:

It would be great to review it and start adding the missing items so this is ready before the WP 6.5 Release Candidate 1.

Reference API

• Blocks
  • supports.interactivity
  • supports.interactivity.clientNavigation
• Directives
  • Framework
    • data-wp-interactive
    • data-wp-ignore
    • data-wp-key
  • State
    • data-wp-context
  • Attributes
    • data-wp-bind--{attribute}
    • data-wp-class--{className}
    • data-wp-style--{styleProperty}
  • Inner content
    • data-wp-text
  • Event listeners
    • data-wp-on--{event}
    • data-wp-on-window--{event}
    • data-wp-on-window--{event}
  • Side effects
    • data-wp-init
    • data-wp-watch
    • data-wp-run
      • Hooks
        • useInit()
        • useWatch()
        • useEffect()
        • useLayoutEffect()
        • useCallback()
        • useMemo()
        • useState()
        • useRef()
  • Templating
    • data-wp-each
      • data-wp-each-child
• Store
  • Client
    • store()
    • getContext()
    • getElement()
    • getConfig()
    • withScope()
  • Server
    • wp_interactivity_state()
    • wp_interactivity_config()
  • Private and read-only stores
• Router
  • Store - core/router
    • state.url
    • actions.navigate()
    • actions.prefetch()
  • Directives
    • data-wp-router-region

---

The Core Concepts guides are optional and could be released after WP 6.5, but they would be a good addition to understanding the mental model behind the Interactivity API.

Core Concepts

• Namespaces
• State
  • Local, global, derived state
  • Server state -> Client state
• Server directive processing
• Declarative vs imperative code (don't mutate the DOM manually!)
• Client-side navigation

---

The readmes should be updated to point to the official documentation, the getting started guide and the Interactivity API discussions for questions.

Readmes

• @wordpress/interactivity package
• @wordpress/interactivity-router package

[juanmaguitar]

The following new issues related to Interactivity API documentation have been created

• Docs: Interactivity API - Move docs from "Reference Guides > Package Reference > @wordpress/interactivity" to "Reference Guides > Interactivity API Reference" #60781
• Docs: Interactivity API - Shape a section in the docs providing a full response to the question "Why it's not possible to just use React?" #60783

[karstengresch]

As a dev user, I'd love to see a full CRUD example (with dynamic form submission) walkthrough, such as https://learn.wordpress.org/course/using-the-wordpress-data-layer/ b.t.w. :)

[juanmaguitar]

Interactivity API Docs are now available from Block Editor Handbook > Reference Guides > Interactivity API Reference

[juanmaguitar]

I have opened #62055 to review and update the README of the @wordpress/interactivity-router package

[WPLake]

@juanmaguitar The current format of the Interactivity API Docs is well-suited for developers with some experience in Gutenberg blocks. However, it lacks basic explanations and a separate guide on how to apply this outside of Gutenberg. We've posted a detailed explanation in our blog that aims to fill the gaps. Wouldn't it be useful to mention this article in the Docs & Examples section?

[juanmaguitar]

Wow! That post is great! Congratulations @WPLake 🙌

WordPress Docs does have a external linking policy that doesn't allow to link resources outside of wordpress.org (with some exceptions), but I would love that some of the explanations and ideas that are covered in your article are also included in the official docs.

Would you like to help shape and improve the official docs?
If so, the best next step would be opening an issue detailing the specific improvements you'd like to see in the docs.
I'd also be happy to connect via Make WordPress Slack (@JuanMa) to discuss any other ways to collaborate to improve the iAPI docs.

[juanmaguitar]

After a conversation with @luisherranz at WCEU about improving the Interactivity API Docs, I've created the following issues that reflect some of the suggested changes we discussed:

• Docs: Interactivity API - Create and "Interactivity API" section under "How to Guides" section and include some initial guides #62922
• Docs: Interactivity API - Create a Core Concepts section for the iAPI #62921
• Docs: Interactivity API - Split "API Reference" page in 5 subsections: Directives, Store, Server API, Client APIs and Router #62920
• Docs: Interactivity API - Create a new page on "Getting Started > Fundamentals of Block Development" to introduce Interactive Blocks using iAPI #62872

Note: They have also been added to the description of this issue

[WPLake]

@juanmaguitar I'm also open to collaboration on the iAPI Docs. I wrote you in Slack DM (@juanma from WPLake) on 18th June. Should we rather chat by email?

[juanmaguitar]

@WPLake, I apologize for the delay in getting back to you.
I've been intensely focused lately on the Docs Squad work for WP 6.6 release 😅
I actually had my response in draft form, but I wanted to provide some background GitHub issues to frame our conversation. I finally completed that today, so I'm happy to continue the discussion via Slack. I'll ping you there today.

[juanmaguitar]

The issue #63570 has been created and added to the list in the description of this issue

[luisherranz]

I've created and added this issue to the list:

• Docs: Interactivity API - document wp_interactivity_state in the API reference #63672