Epic: Interactivity API - public 1.0 version

[luisherranz]

• Part of Block API #41236.

In More core blocks and new store() API, we first worked on preparing Core blocks for WP 6.4, including the new enhanced pagination of the Query block, and after the release of WP 6.4, we also worked on the migration of the new store() API.

For this iteration of the Interactivity API, we want to focus on the preparation of a 1.0 version that can be released publicly in WordPress Core and serve as the base for future enhancements.

We also want to consolidate here the work of the Tracking Issue: Server Directive Processing to keep all the implementation work under the same issue, but we will keep tracking the documentation-related tasks in the Documentation Tracking Issue.

Tasks

This is the list of initial tasks, although we will edit this post as we progress and discover other things that we need to do.

• Directives
  • Implement the wp-run directive
    • Directives to execute a callback in the scope of the component #51863
    • Interactivity API: add wp-run directive and useInit & useWatch hooks #57805
  • Expose the useInit and useWatch hooks
    • Interactivity API: add wp-run directive and useInit & useWatch hooks #57805
  • Add data-wp-on-window and data-wp-on-document directives
    • Interactivity API: Add wp-data-on-window and wp-data-on-document directives #57931
  • Remove the navigation-link directive
    • Interactivity API: Remove wp-data-navigation-link directive #57853
  • Remove the wp-slot and wp-fill directives if we don't finally need them
    • Interactivity API: Remove data-wp-slot and data-wp-fill #57854
  • Prevent using components in data-wp-text, only strings
    • Interactivity API: Prevent the use of components in wp-text #57879
  • Remove support for element state until naming and use cases are clearer
    • Interactivity API: Remove unused state and rename props to attributes in getElement() #57974
  • Add support for element attributes
    • Interactivity API: Remove unused state and rename props to attributes in getElement() #57974
  • Update Preact to the latest version and remove the custom role logic in our codebase
    • Interactivity API: Update preact, @preact/signals and deepsignal dependencies #57891
  • Expose withScope and add support for async functions (generators)
    • Interactivity: Export withScope() and allow to use it with asynchronous operations. #58013
  • Add support for wp-each
    • Interactivity API: Add wp-each directive #57859
  • Put all the private exports behind a locked proxy
    • Interactivity Router: Fix initial page cache #58496
  • Remove the non-default wp-context suffix
    • Interactivity API: Remove non default suffix data wp context processing. #58664
  • Use data-wp-interactive="namespace"
    • Interactivity API: Support setting a namespace using a string in data-wp-interactive #58743
  • Review the @wordpress/interactivity exports
    • Interactivity API: Limit the exported APIs #58864
  • Remove the wp-body directive
    • Image block: refactor and remove data-wp-body #58835
  • Fix: Improve the way we merge contexts after navigation
    • Interactivity API: Improve context merges using proxies #59187
  • Fix: Prevent proxifying non-plain objects
    • Interactivity API: Only add proxies to plain objects inside the store #59039
• Store
  • Re-implement wp_store as wp_initial_state
    • Interactivity API: Implement wp_initial_state() #57556
  • Fix: Merge new SSR state on client-side navigation (discussion)
    • Interactivity API: Fix navigate() issues related to initial state merges #57134
• Router
  • Create the core/router store and move the navigate and prefecth actions there
    • Interactivity API: Create @wordpress/interactivity-router module #57924
  • Code-split the core/router store in @wordpress/interactivity/router
    • Interactivity API: Create @wordpress/interactivity-router module #57924
  • Rename data-wp-navigation-id to data-wp-router-region
    • Interactivity Router: Replace data-wp-navigation-id with data-wp-router-region #58191
  • Add a top loading bar on navigation
    • Interactivity Router: Move ARIA live region and loading bar to the Interactivity Router  #58377
  • Add a screen reader announcement on navigation
    • Accessibility: Announce client-side navigation to screen-readers by default #55129
    • Interactivity Router: Move ARIA live region and loading bar to the Interactivity Router  #58377
  • Expose a way to trigger virtual pageviews, like state.url in the core/router store
    • Interactivity Router: Move ARIA live region and loading bar to the Interactivity Router  #58377
  • Fix: Fix the initial page cache (code)
    • Interactivity Router: Fix initial page cache #58496
  • Populate state.url from the server
    • We finally decided to maintain the code that adds it from the core/router store in JS.
  • Switch to global config config['core/router'].regionNavigation = false
    • Interactivity API: Allow global configs for namespaces #58749
  • Fix: Add data-wp-key to the page numbers
    • Pagination Numbers: Add data-wp-key to pagination numbers if enhanced pagination is enabled #58189
• Block metadata
  • Add clientNavigation and interactive to block supports metadata.
    • Interactivity API: Add block supports for clientNavigation and interactive properties on block.json schema. #58132
  • Move block script module registration to the render_callback and use wp_scripts_get_suffix
    • Interactivity API - Blocks: Move interactivity registration to render #58678
  • Use private stores for all the interactive core block stores
    • Interactivity API: Mark all core block stores as private #58722
• Server Directive Processing
  • Make sure we only process the directives once
    • Server directive processing: Process only root blocks #55739
  • Sort directives by priority
    • Server directive processing: Stop processing non-interactive blocks #56302
  • Add support for data-wp-interactive='{ "namespace": "..." }'
    • Interactivity API: Implement wp_initial_state() #57556
  • Improve block identification (check the block name before the md5)
    • Interactivity API: Implement wp_initial_state() #57556
  • Render the root interactive blocks
    • Interactivity API: Render the root interactive blocks #57729
  • Encapsulate everything into a single function wp_interactivity_process_directives()
    • Interactivity API: Server Directive Processing Refactor #58066
  • Make sure it bails out on unbalanced tags
    • Interactivity API: Server Directive Processing Refactor #58066
  • Add tests for edge cases
    • Interactivity API: Server Directive Processing Refactor #58066
  • Add processor for wp-each
    • Interactivity API: Server Directive Processor for data-wp-each #58498
  • Optional: Add a helper function to add data-wp-context on PHP
    • Interactivity API: Server Directive Processing wordpress-develop#5953
  • Optional: Add support for private stores
    • Private store references #51596
    • Interactivity API: Mark all core block stores as private #58722
    • Interactivity API: Fix state intialization for asynchronous private stores #58754
  • Fix: Skip SVG and MathML (instead of bail out)
    • Interactivity API: Skip instead of bail out if HTML contains SVG or MATH wordpress-develop#6091
• Debug
  • Optional: Show an error in the browser console when the server directive processing fails
    • Interactivity API: Server Directive Processing wordpress-develop#5953 (comment)'
• Code Quality
  • Optional: Typscript the entire runtime. Add comments to functions. Etc.
    • Interactivity API: Migrate everything to TypeScript, add missing comments and remove the use of "we" #58718

[cbravobernal]

The directive processing of only interactive blocks is ready for review. I will add more tests during this week.

[felixarntz]

Related to the server-side directive processing and the above PR #56302, are there any plans to provide an API function that is decoupled from blocks? I think there are many use-cases (primarily classic "hard-coded" HTML in core, plugins, and themes) that could use the Interactivity API. If such use-cases could then call a simple function to process the directives on the HTML string, that would be really helpful.

Potentially the function gutenberg_process_interactive_html() introduced in #56302 could be what I'm looking for? As far as I can tell, the only block specific part is $inner_blocks which could be omitted?

[luisherranz]

@felixarntz yeah, we're still trying different things here. To be honest, I'm not very happy with the current approach. And as you say, it's quite coupled with blocks.

I think we can simplify it to process only on the "root interactive blocks" and try to encapsulate everything in a single function. Maybe something like this that also classic themes could use:

$html = do_interactivity( $html );

To do so, we need to get rid of all the things that depend on knowing which part of the HTML belongs to which block during the processing (like private stores), but I think it's doable and it will simplify things.

What do you think?

[felixarntz]

Thanks @luisherranz, that sounds like a good plan to me. I have to admit, my understanding of private stores is quite limited still. But what you're saying sounds solid as far as I can assess.

Regarding a function name, I'd prefer to do away with the "do" prefix. While it's sort of common for some WP processing functions, I think it's also somewhat legacy. I would find something like process_interactivity or parse_interactivity or parse_interactivity_directives more suitable. But a function name is probably the last challenge in this 😆

[luisherranz]

Haha, sure. That's because I was thinking about do_blocks, but those names sound good to me. Let's see if we can condense everything into a single function 🙂

[cbravobernal]

Added a PR to render the root interactive blocks in Server Directives Processing. Ready to review!

• Interactivity API: Render the root interactive blocks #57729

[DAreRodz]

I created a PR to implement the data-wp-run directive. I saw it convenient to include also the hooks useWatch and useInit in the same PR. Ready for review.

• Interactivity API: add wp-run directive and useInit & useWatch hooks #57805

[luisherranz]

The PR with wp_initial_state was merged:

• Interactivity API: Implement wp_initial_state() #57556

[cbravobernal]

Created two PRs that remove directives that are not being used:

• Interactivity API: Remove data-wp-slot and data-wp-fill #57854
• Interactivity API: Remove wp-data-navigation-link directive #57853

I labeled them as breaking changes, in case some external developers have been using them.

[DAreRodz]

The wp-run directive implementation, the new useWatch and useInit hooks, and the scoped version of all callback-based hooks have been recently merged.

• Interactivity API: add wp-run directive and useInit & useWatch hooks #57805

[DAreRodz]

I've opened a new PR to move all the logic related to the ARIA live region and the loading bar from the Query block to the Interactivity Router. Ready for review.

• Interactivity Router: Move ARIA live region and loading bar to the Interactivity Router  #58377

[Tropicalista]

Can someone please clarify what is the name of the function for a default store in PHP?

In previous release was wp_store, then changed to wp_initial_state. Now it seems it's renamed to wp_interactivity_state.

Can we please specify this in docs as well?

#58436

[luisherranz]

@Tropicalista: yes, we've renamed the function. I'll make a PR to update the docs once GB 17.6 is released with the final name.

Please follow the changelog and breaking changes discussion to get the latest updates on how the API evolves.

[DAreRodz]

I have opened a draft PR to fix the initial page cache in the @wordpress/interactivity-router module.

• Interactivity Router: Fix initial page cache #58496

[luisherranz]

I opened a PR that adds a server processor for data-wp-each:

• Interactivity API: Server Directive Processor for data-wp-each #58498

[luisherranz]

Small update.

• The last two server directive processors (data-wp-each and data-wp-router-region) have been merged.
• The navigate function now triggers the loading bar and screen reader announcement by default.

Remaining tasks:

• Query block: switch from data-wp-navigation-disabled to config['core/router'].clientNavigation = false
• Image block: see if we can remove the data-wp-body directive.
• Other small tweaks.

[cbravobernal]

I added two more PRs:

• Interactivity API - Blocks: Move interactivity registration to render #58678
• Interactivity API: Remove non default suffix data wp context processing. #58664

[cbravobernal]

Added a PR with some small changes in comments. And refactors to TS.

• Interactivity API: Migrate everything to TypeScript, add missing comments and remove the use of "we" #58718

[DAreRodz]

I've created a PR to make all core block stores private.

• Interactivity API: Mark all core block stores as private #58722

It includes a bugfix that solves a problem with the async initialization of private stores.

[luisherranz]

I've opened a PR to support data-wp-interactive="myPlugin".

• Interactivity API: Support setting a namespace using a string in data-wp-interactive #58743

[DAreRodz]

Here, a draft PR that implements global configs in the JS runtime:

• Interactivity API: Allow global configs for namespaces #58749

It also gets rid of the data-wp-navigation-disabled attribute we were adding to Query blocks when they contain unsupported blocks. Instead, a property clientNavigation inside the core/query config is used.

EDIT: the PR is ready for review now.

[DAreRodz]

I have updated the task list to mark "Populate state.url from the server" as complete, explaining that we decided not to implement that and keep the logic that initializes it from JS in @wordpress/interactivity-router.

[DAreRodz]

This PR limits the exposed API from @wordpress/interactivity:

• Interactivity API: Limit the exported APIs #58864

[luisherranz]

I opened a PR to remove the data-wp-body directive and refactor the Image block to add the overlay using wp_footer instead:

• Image block: refactor and remove data-wp-body #58835

[mtias]

Regarding one meta aspect of how we communicate this functionality more broadly, I think Interactivity API is ok as the technical aspect for developers, but when we talk broadly about what it does I think we should refer to it as Interactions. Interactions is the feature, and it's powered by this new developer API.

So similar to block API -> blocks we'll have interactivity API -> interactions. I find that clearer and easier than interactivity on its own, but curious what others think. I don't believe this has any material considerations on namespace issues at the code level, except perhaps the possibility of renaming the entry package to @wordpress/interactions.

[ajgagnon]

Regarding one meta aspect of how we communicate this functionality more broadly, I think Interactivity API is ok as the technical aspect for developers, but when we talk broadly about what it does I think we should refer to it as Interactions. Interactions is the feature, and it's powered by this new developer API.

So similar to block API -> blocks we'll have interactivity API -> interactions. I find that clearer and easier than interactivity on its own, but curious what others think. I don't believe this has any material considerations on namespace issues at the code level, except perhaps the possibility of renaming the entry package to @wordpress/interactions.

This would need careful consideration, for sure. Having 2 names for the same functionality can also make things less clear in some cases. There is currently this issue with people referring to the "WordPress Block Editor" as "The Gutenberg Editor". Maybe `interactivity API -> interactivity"? Just a thought.

[cbravobernal]

Added a PR to fix directives not being processed if the HTML contained a SVG or a MATH.

• Interactivity API: Skip instead of bail out if HTML contains SVG or MATH wordpress-develop#6091

[fabiankaegy]

Now that we are past the Beta 1 cut off point I'm removing this tracking issue from the 6.5 Project board. From now on the board should only contain individual bugs that we want to still fix before 6.5 gets released.

[gziolo]

Should we also close the issue an open separate issues for remaining tasks so those applicable can be put on the 6.5 board and tackled before 6.5 Beta 3 scheduled for Tuesday next week?

[cbravobernal]

I will miss this tracking issue 😅, but yep, I will do that.