Documentation for the Interactivity API - Tracking Issue

juanmaguitar commented 11 months ago

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 https://github.com/WordPress/gutenberg/discussions/51928, and we'll coordinate everyone's efforts.

Tasks

Tasks related to Interactivity API Docs are labelled with [[Feature] Interactivity API] & [Type] Developer Documentation]](https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+label%3A%22%5BFeature%5D+Interactivity+API%22+label%3A%22%5BType%5D+Developer+Documentation%22)

juanmaguitar commented 7 months ago

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

They're also part of https://github.com/WordPress/gutenberg/issues/53740

luisherranz commented 5 months ago

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
- [x] supports.interactivity
- [x] 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 commented 2 months ago

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

karstengresch commented 2 months ago

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 commented 2 months ago

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

juanmaguitar commented 1 month ago

I have opened https://github.com/WordPress/gutenberg/issues/62055 to review and update the README of the @wordpress/interactivity-router package

WPLake commented 1 month ago

@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 commented 1 month ago

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 commented 1 week ago

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:

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

WPLake commented 1 week ago

@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 commented 1 week ago

@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.

WordPress / gutenberg