Interactivity API and extensibility

[michalczaplinski]

"Extensibility" is one of the touted benefits of using the Interactivity API.

However, developers can only extend the API in very limited ways. I want to discuss 2 possible ways of extending the Interactivity API here:

1. Rendering custom Preact components
2. Creating custom directives

Custom components

Previously, as discussed in #60418, it was possible to pass a Preact component to a data-wp-text directive, which would render that component on the front end. However, this functionality was later removed in #57879. This was a sound decision at the time and aligns with the "cautious" philosophy of only exposing the minimum necessary primitives in any new API and only adding new ones once there is sufficient need from the users. This minimizes the risk of shipping the wrong abstraction and lessens the backward compatibility burden if the new API is indeed inadequate in some way.

Without concern for "how" the components API would look (data-wp-component or something else?) I would like to discuss the merits of exposing it (or not exposing it).

👍 "For" components

Users are inevitably going to want to use Preact components in their code. It might be because they have a legitimate use case for functionality that does not have a meaningful representation on the server. It might be because they are more comfortable writing components. They will inevitably find workarounds (like this one), so it would be better to expose an official way to ship components because:

• There is no need for third-party hacks; we can even provide utilities to make it easier to render those components.
• This approach also aligns with WordPress's general philosophy of being as "hackable" and "extensible" as possible.

👎 "Against" components

Using Preact components together with the Interactivity API is often an antipattern. The vast majority of use cases for the Interactivity API do not require using Preact components and can likely be accomplished with just the Interactivity API. Thus, there is a significant risk that we are encouraging bad practices by making components easy to use.

An API should guide users towards the pit of success, providing guardrails that prevent abuse and encourage best coding practices.

Custom directives

To be brief, most of the discussion above also relates to custom directives. The difference is that creating custom directives gives users even more freedom than just allowing components (you can create a custom directive that renders components, but not the other way around).

In principle, we could expose a registerDirective() function that is different from the directive() function in the framework. This hypothetical registerDirective() function might be more limited in functionality and scope and, e.g., disallow returning components from it or perform additional validation checks.

---

Personal opinion: We should allow for the creation of custom components. I'm not convinced about custom directives yet, as they are even more powerful and require more thought about how to approach them. However, as this is a discussion of the philosophy of how we write software, I'd like to hear people's thoughts on this, especially if they disagree 🙂 .

[sirreal]

This is an important discussion to have, thanks for starting it. To answer this type of question, let's build. Let's figure out the need to satisfy and explore the proposed solutions.

What is difficult or impossible to build right now? I'd love to hear ideas from the community about that. It will help to understand what needs should be satisfied with extensibility.

Let's build that. We can prototype with the proposed approaches so we can analyze their tradeoffs. That will inform this discussion and decision.

[cbravobernal]

I agree with this answer. The API has been public only for a couple of months.

My opinion is that we should wait for the API to be more mature and used in the WordPress ecosystem.

Also, adding new features will increase the learning barrier.

[luisherranz]

(data-wp-component or something else?)

I've been thinking about this, and I believe the name of this directive should be very explicit, already conveying the disadvantages of using it. Something like data-wp-client-only-component.

Similar to the upcoming data-wp-dangerous-html.

[fabiankaegy]

Thanks for opening this discussion :)

In addition to the topics you've outlined, I would like to highlight another area of extensibility. As it stands today, the Interactivity API is very powerful when building custom blocks. You have full control over the markup and, therefore, can easily add your own store/directives and just build whatever you want.

However, it is very difficult to use the Interactivity API today to extend the behavior of core blocks/patterns with custom interactivity. There are a few things that contribute to this:

1. All the core stores are locked, so it is impossible to interact with them.
2. It is not clear to me how one would connect a custom store with a core block that already has its own store.
3. Given that pretty much everything in a block theme is a group block, it is very hard to attach your interactivity to the correct spot. (Targeting is hard with all the generic blocks)
4. There doesn't seem to be a great solution for "sprinkling in" interactive behavior from a global store at the moment.

Here are some brief examples for each of these to hopefully better explain my point:

1. The core navigation block already contains a state for whether it is open or closed. It also has a method in its story to open/close it. Today, it is not possible to access that, so when you want to have a more complex interaction, you are out of luck and need to manually replicate the markup changes that core is performing...

2. Looking at the Navigation block again. Because it has locked its store the only way to interface with it is via a custom store. But that cannot get added to the element because the block already has a store 🤔

3. A common design pattern for sticky headers is that the header is sticky only for a short threshold at the top of the page and then animates out. But when the user starts to scroll back to the top or reaches the very bottom of the page, the header animates back in. This is not something one can achieve with the position: sticky of the group block. So, the way we usually do this is by adding some custom JS to the header template part that handles all this logic for us. It would be much easier / nicer to use the interactivity API for this. But given that the template part is just one of many, and the group that has the sticky position is just one of many, it is very cumbersome to actually target the block in the render_block hook to add the directives to the markup. Registering the store for it is also a lot of manual work because there is no easy way to enqueue a custom view-script-module only when that block is used on the page.

4. Something we commonly use JS for is triggering more complex animations. These animations should only trigger when an element enters the viewport. The best way to do this is to add an Intersection Observer to an element and trigger the animation when the element intersects. Today there doesn't seem to be a way to have a global animation store that would allow me to add some kind of animation directives to any elements. Similarly if I have an action I want to happen on click across a few different block, I've not yet found a way to easily share actions between different blocks.

I hope these examples help showcase some of the challenges I'm currently running into :)

[gziolo]

That's a great list of use cases that should be looked into when shaping the improved extensibility story. Thank you, @fabiankaegy for sharing your experience.

You have full control over the markup and, therefore, can easily add your store/directives and just build whatever you want.

One clarification. You can declare new stores but only consume existing directives. This discussion touches on the potentially new capability to allow developers to define custom directives. That could help with encapsulating a store that can be used with multiple blocks like in your sticky header example. The assets for custom directives could also be automatically loaded only when actually used on the page in HTML output, which would resolve the issue you mentioned about enqueueing the script.

[luisherranz]

I hope these examples help showcase some of the challenges I'm currently running into :)

They do, thank you 🙂

All the core stores are locked, so it is impossible to interact with them.

Making them private was a temporary measure to ensure that the Core blocks' stores are correctly shaped before making them public. So the plan isn't to keep them private; rather, we now need to determine what extensibility requirements exist and which parts of those private stores should become public.

Something we commonly use JS for is triggering more complex animations. These animations should only trigger when an element enters the viewport. The best way to do this is to add an Intersection Observer to an element and trigger the animation when the element intersects.

There is no problem in using the Intersection Observer with the Interactivity API to trigger an animation, is it?

Also, users can create hooks to reuse these types of functionalities:

<div
  data-wp-run="callbacks.isInView"
  data-wp-class--animate-me="context.animate"
>
  Target element
</div>

const useInView = (options = {}) => {
  const [inView, setInView] = useState(false);

  useEffect(() => {
    const { ref } = getElement();
    const observer = new IntersectionObserver(([entry]) => {
      setInView(entry.isIntersecting);
    }, options);

    if (ref) {
      observer.observe(ref);
    }

    return () => ref && observer.unobserve(ref);
  }, []);

  return inView;
};

store("...", {
  callbacks: {
    isInView: () => {
      const ctx = getContext();
      const isInView = useInView();

      // This changes the class and triggers the animation.
      ctx.animate = isInView;

      useEffect(() => {
        if (isInView) {
          console.log("Element is inside the viewport");
        } else {
          console.log("Element is outside the viewport");
        }
      });
    },
  },
});

You can see it in action here (although keep in mind that this example is using an old version of the Interactivity API).

You can see it in action here.

We could also add some of these hooks to the official library if they are common.

Today there doesn't seem to be a way to have a global animation store that would allow me to add some kind of animation directives to any elements.

In the future, we could create a directive similar to Svelte's animate, to add some simple animations:

<div animate:flip={{ delay: 250, duration: 250, easing: quintOut }}>
	...
</div>

<div
  data-wp-animate--flip='{ "delay": 250, "duration": 250, "easing": "quintOut" }'
>
  ...
</div>

Similarly if I have an action I want to happen on click across a few different block, I've not yet found a way to easily share actions between different blocks.

Can you give more details on how you're trying it and what's not working for you?

But given that the template part is just one of many, and the group that has the sticky position is just one of many, it is very cumbersome to actually target the block in the render_block hook to add the directives to the markup. Registering the store for it is also a lot of manual work because there is no easy way to enqueue a custom view-script-module only when that block is used on the page.

I think this touches on something we were experimenting with at the beginning, back then called Behaviors, which would be a system to add interactivity to blocks in a similar way as is being done with styles with Block Supports and Global Styles. So a third-party developer could add interactivity to an existing block, and that interactivity would show in the UI and could be selected for a specific block. Or for a block type using Global Styles. Enqueueing the CSS and JavaScript of the selected Behavior would happen automatically when that Behavior is selected for a block.

The main technical issue with these Behaviors is the difficulty in identifying when two may conflict. If third-party developers create these Behaviors, users might activate two that are incompatible simultaneously. Restricting it to one Behavior per block is also limiting because some Behaviors might work well together.

Will that make sense?

[fabiankaegy]

@luisherranz Sorry for not getting back to you on this sooner. And yes the main pain point that I was trying to outline and that I am running into more and more is how we actually use some globally available behavior that should get applied to a bunch of different blocks at once.

If I for example want to add an animation as a block extension that users can apply to any block I would need to mark ans individual block as an interactive region. But that block may already be interactive.

Essentially I wold love to have a way to more easily add "global" directives that I can also add to any other block via a render_block filter

[luisherranz]

But given that the template part is just one of many, and the group that has the sticky position is just one of many, it is very cumbersome to actually target the block in the render_block hook to add the directives to the markup

Another pattern that might work and that @r-chrzan has applied very well in this example, is registering a variation of the general block, and making that the target of the render_block.

https://github.com/r-chrzan/instant-search-interactivity/blob/8795e02ba35811a8829384effdd0371969d0c13d/src/index.js#L39-L57

Essentially I wold love to have a way to more easily add "global" directives that I can also add to any other block via a render_block filter

Are you using the HTML Tag Processor to inject the directives? If so, you can check if there's a data-wp-interactive directive before adding it.

$p = new HTML_Tag_Processor( $content );

if ( $p->next_tag() ) {
  if ( ! $p->get_attribute( 'data-wp-interactive' ) ) {
    $p->set_attribute( 'data-wp-interactive', true );
  }
}

Global directives can be added with the following syntax to target a specific namespace:

$p->set_attribute( 'data-wp-on--click' 'myGlobalStoreNamespace::actions.someGlobalAction' );

@westonruter was working on something similar, but encountered the problem that, in order for the attributes to be truly global and never have name collisions, the attribute name also has to be unique. We started this discussion to see what syntax we could use. It would be great if you could add your feedback 🙂

[sirreal]

I have an interesting case. It is impossible to render a true tree structure using the Interactivity API as it is today. What's lacking is some concept of recursion. I could solve that with the right extensibility points.

Consider my tree:

interface Node {
  nodeType: string,
  childNodes: Node[]
}

I'd like to create some HTML like this:

<span data-wp-text="node.nodeType"></span>
<ul>
  <template data-wp-each="node.childNodes">
    <li>
      <!-- here is where we should recurse -->
      <span data-wp-text="context.item.nodeType"></span>
      <ul>
        <template data-wp-each--child="context.item.childNodes">
          <!-- … -->
        </template>
      </ul>
    </li>
  </template>
</ul>

This is rather trivial to implement with recursion, but it's impossible (or close enough) that the Interactivity API today is completely unsuited to this.

I'd like to define a custom directive like this:

<template data-wp-node="state.tree"></template>

Where that directive renders this (see how it self-references to recursively handle the tree):

<span data-wp-text="context.node.nodeType"></span>
<ul>
  <template data-wp-each="context.node.childNodes">
    <li>
      <!-- vvv here we self-reference to recurse vvv -->
      <template data-wp-node="context.item"></template>
    </li>
  </template>
</ul>

[luisherranz]

No. It was meant as an example of a PHP component using PHP functions 🙂

Using this sort of "PHP components" is a temporary way to solve what you said in the initial comment, because you can create a function that calls itself recursively:

It is impossible to render a true tree structure using the Interactivity API as it is today. What's lacking is some concept of recursion.

Does that make sense?

[sirreal]

It's not clear how that addresses the problem. You mean that the recursion is handled by PHP functions that produce HTML? That will only work on server render, but not in cases where we change the tree on the client.

[luisherranz]

I see. So in the client, you'd add more depth to the array, which needs to add more nested template elements on-the-fly, right?

That's an interesting use case indeed 🙂

[sirreal]

Exactly. Some form of recursion or self-reference solves it trivially but other implementations are hard or impossible.

[luisherranz]

I've added it to the roadmap (which we haven't updated for a while, and I'd like to review…).

[joshuatf]

In WooCommerce, we've considered using the interactivity API in areas of the admin such as the product editor. This is purely conceptual and full disclosure- not something that we've even explored fully, but I wanted to offer another perspective in favor of components.

The interactivity API in this case allows us to sprinkle in interactivity within the existing page structure without replacing the entire application immediately with a React app. This means that we can also continue to use existing hooks for extensibility and potentially add basic interactivity to content rendered from those hooks using the HTML processor API. Additionally, the interactivity API requires less mental overhead and build processes for 3PDs who do not yet have those in place.

<div class="form-field">
    <label>Regular price</label>
    <input type="text" data-wp-on--change="actions.handleInputChange" data-wp-bind--value="state.product.regular_price" />
</div>
<?php do_action( 'woocommerce_product_options_pricing' ); ?>

However, since we also want consistency within the WordPress admin, the product editor relies heavily on the @wordpress/components package to render inputs. Being able to render components alongside interactive elements provides a nice stopgap as we transition from a legacy experience to a more modern one.

But having some level of consistency in the "components" (even if those are not React) is important in the case of the product editor to improve the UI/UX. I can see an argument where that could be mostly handled in PHP and is less the responsibility of the Interactivity API, but having these readily available in the Interactivity API is both convenient and offers a level of progressive enhancement for applications transitioning between experiences.