Interactivity API - Iteration for WP 6.6

[DAreRodz]

• Part of Block API #41236.

---

We completed everything for the first public release of the Interactivity API in WordPress 6.5. Now, during the next iteration―which is going to be shorter―, we aim to focus on improving the current API without releasing new features. This includes enhancing the developer experience (especially during debugging), better test coverage and code quality, as well as fixing any reported bugs.

Note that the list is expected to be modified. I've also added optional tasks we can work on if we find the time.

Tasks

• Bug fixes
  • Interactivity: Return useMemo and useCallback hooks #60474
  • Interactivity API: Allow multiple event handlers for the same type with data-wp-on. #60661
  • Support multiple data-wp-on-window or data-wp-on-document directive with the same event #60683
    • Interactivity API: Allow multiple event handlers for the same type with data-wp-on-document and data-wp-on-window. #61009
  • Interactivity API: Ignore ignore directives on the server wordpress-develop#6405
  • Interactivity: Ensure ignore directives are stable #60744
• Debugging
  • Interactivity API: Debug - Warning about Server Directives Processing errors. #60035
    • Interactivity API: Add debug notice for SSR wordpress-develop#6413
  • Interactivity API: Include preact/debug when WP_DEVELOPMENT_MODE is enabled. #59829
  • Interactivity API: Debug - Show directive names included in each Directives component on Preact’s debug tools #60049
  • Better error logging
    We need to locate which errors we need to inform about. Examples:
    • Throw an error when no namespace is specified when executing a directive.
    • directives incorrectly written

      This one is tricky. In the future, missing directives can be hydrated later on, or not have a callback associated, thus being undefined in the directives registry.

    • undefined props from the store

      Similar case as the previous one; missing attributes from the store can be added later on. We need to ensure that reading undefined attributes doesn’t raise any errors.

• Code quality
  • Document data-wp-ignore directive
  • Move the whole runtime to TypeScript
    • Interactivity API: Migrate everything to TypeScript, add missing comments and remove the use of "we" #58718
    • Interactivity API refactor to TypeScript (utils & kebabToCamelCase) #60149
    • Interactivity: Strict type checking #59865
  • Move @wordpress/interactivity-router to TypeScript
  • Add missing JSDoc comments
  • Optional: Unify state and context proxies with deepsignal
• Testing
  • Increase test coverage, add edge cases.
  • Add unit tests (utils, toVdom, etc.)
• Router
  • Optional: Load new scripts and style assets on client navigation
  • Optional: Interactivity Router: Support Handling navigate() Failure States #59856
  • Experiment: Full client-side navigation
    • Experiment: Add full page client-side navigation experiment setting #59707
• Directives
  • Optional: Allow directives to be loaded asynchronously
    • Interactivity API: Allow async directive registration #60670
  • Optional: Add the data-wp-show directive
  • Allow static blocks in wp_kses function.
• Performance
  • Optional: Interactivity API: Event directives cannot be passive #58705
  • Experiment: Interactivity API: Defer hydration until node is scrolled near the viewport #58284
• Enhancements
  • Allow blocks with interactivity support inside core/query (useUnsupportedBlocks) #59752
    - Update the query block to permit non-core interactive blocks #60006
  • Interactivity API: Add server derived state getter handling wordpress-develop#6394
  • https://core.trac.wordpress.org/ticket/61039 - handle array or object access in PHP directive processing

[felixarntz]

@DAreRodz @gziolo What's the best path to consider additional workstreams for the Interactivity API for 6.6?

Context is that @westonruter and myself have been exploring ideas to facilitate better INP performance centrally via the Interactivity API. For instance, we could automatically yield certain actions and callbacks to the main thread to reduce contention between multiple event listeners. We're close to formalizing our proposal in an issue, and it would be great to eventually include this effort here, if the team is on board.

One of the changes we're proposing may require a BC break in the API which we could handle with a deprecation strategy, but it would also benefit from being implemented sooner than later, now that the API is still very new and not yet as widely adopted outside of core.

[DAreRodz]

Hey @felixarntz, thanks for raising this up! 😊

I'm unsure what would be the "best path" (maybe @gziolo could help), but as this tracking issue is meant to be flexible, I would be happy to include your work. Let's wait for the proposal to see if we can have it ready for WP 6.6 and how the mentioned breaking changes could impact the current API.

[gziolo]

That sounds excellent, @felixarntz. I'm looking forward to seeing the proposal.

@DAreRodz, the Iteration issues mostly bring focus and increase the visibility of what to expect in WordPress 6.6, but it doesn't mean we can't change it. In practice, we should always be open to changing the plans based on the feedback and discoveries from the community experts 😍

[sirreal]

The ability to use existing WordPress Scripts from Script Modules is one of the most impactful things we can work on for the Interactivity API. Anything built with the Interactivity API must be a script module, so although it's not strictly Interactivity API, resolving this ticket for script and module interoperability seems very important: https://core.trac.wordpress.org/ticket/60647

[sethrubenstein]

Second @sirreal calls for WordPress scripts. We use wp-api-fetch and wp-url with interactive blocks, a lot. Making that easier from a dev tooling perspective to automatically enqueue those scripts would be greatly appreciated.

[ermincelikovic]

Is there any chance to get interactivity api outside of blocks? For example in custom php templates?

[felixarntz]

@ermincelikovic While I believe it's not documented, it should already be possible. The main caveat is that by default custom PHP templates wouldn't be processed server-side, so you have to make sure the attributes that are dynamic via the Interactivity API are initialized with their correct value.

As a proof of concept, I have been working on WordPress/wordpress-develop#5795 where I am using the Interactivity API for all dynamic functionality of the Twenty Twenty-One theme. Maybe that's helpful.

[luisherranz]

default custom PHP templates wouldn't be processed server-side, so you have to make sure the attributes that are dynamic via the Interactivity API are initialized with their correct value

You can process them using wp_interactivity_process_directives 🙂

[ermincelikovic]

default custom PHP templates wouldn't be processed server-side, so you have to make sure the attributes that are dynamic via the Interactivity API are initialized with their correct value

You can process them using wp_interactivity_process_directives 🙂

This looks great!
How would I import { store, getContext } from "@wordpress/interactivity"; within a context of php template or a traditional script.js file in the theme though?

EDIT:
Just found out that script modules are also introduced in 6.5:
https://make.wordpress.org/core/2024/03/04/script-modules-in-6-5/

[cbravobernal]

I've added the suggestions in Typescripting utils PR. Ready to be reviewed again.
#60149

[sirreal]

How would I import { store, getContext } from "@wordpress/interactivity"; within a context of php template or a traditional script.js file in the theme though?

@ermincelikovic The @wordpress/interactivity script module is only available to other script modules at this time. Using it from WordPress scripts is not supported at this time. See this ticket for details.

[DAreRodz]

I've added two PRs to the description above.

• Interactivity API: Allow multiple event handlers for the same type with data-wp-on. #60661
• Interactivity API: Allow async directive registration #60670

The first one could be considered a bug fix (I've added it under that category), and so be released in a minor WP release.

[DAreRodz]

The fix for data-wp-on is merged.

• Interactivity API: Allow multiple event handlers for the same type with data-wp-on. #60661

I've also opened an issue to fix the same problem in data-wp-on-window and data-wp-on-document.

• Support multiple data-wp-on-window or data-wp-on-document directive with the same event #60683

[fabiankaegy]

In addition to #60035 I'd love to see some more useful debugging for the following areas:

• output a warning when you use directives in the markup of a block that doesn't have the interactivity support enabled

• add better client side errors when you try to access a property on a store that doesn't exist

• add a guide for how to connect the preact dev tools to the interactivity API

---

Besides debugging here are some other things that I would love to see in the 6.6 cycle.

• some documentation for working with external stores / making a store extensible

• refine clarity in documentation of what the difference between callbacks and actions are

• add documentation for client side routing like the query block does it

[sirreal]

I've added WordPress/wordpress-develop#6394 for server-side derived state. It's ready for review.

[sirreal]

I've just added 3 items related to data-wp-ignore directive.

• It needs to be documented, it's not in the API Reference right now.
• Interactivity: Ensure ignore directives are stable #60744
• Interactivity API: Ignore ignore directives on the server wordpress-develop#6405

I think there's a bug with the server processing of ignore directives I'm attempting to fix in WordPress/wordpress-develop#6405. I think that nodes with that attribute and their descendants should be ignored completely, no processing should happen on or under a node with data-wp-ignore. @cbravobernal or @DAreRodz can you confirm?

Right now ignore directives are not handled on the server, so those nodes and their descendants are processed. I discovered that while working on tests for #60744.

[sirreal]

I've created this ticket to handle property access on PHP objects in interactivity state, only arrays are well handled at the moment: https://core.trac.wordpress.org/ticket/61039

[cbravobernal]

I've created a PR to add a couple of warnings if Server Directives processing fails.

• Interactivity API: Add debug notice for SSR wordpress-develop#6413

[cbravobernal]

Created a PR to handle multiple document and window events in the same element.

• Interactivity API: Allow multiple event handlers for the same type with data-wp-on-document and data-wp-on-window. #61009