Mechanism to detect blocks compatible with the Interactivity API

[luisherranz]

Sometimes, we are going to need to know which blocks are compatible with the Interactivity API to make sure that the specific features that require all the blocks to be compatible, can be activated safely. For that, we need to figure out a mechanism to detect if a block is compatible with the Interactivity API.

Regarding this, there are three types of blocks:

• Non-interactive: blocks that don't contain any frontend JS logic.
• Interactive, using the Interactivity API: interactive blocks that use the Interactivity API for their interactivity.
• Interactive, not using the Interactivity API: interactive blocks that don't use the Interactivity API for their interactivity.

To simplify talking about each block type, let's call them:

• Non-interactive: Non-interactive blocks
• Interactive, using the Interactivity API: Interactivity API blocks
• Interactive, not using the Interactivity API: Legacy Interactive blocks

Only the Non-interactive and Interactivity API blocks are compatible.

We can detect Interactive API blocks because they are marked with supports.interactivity: true in the block.json.

{
  "supports": {
    "interactivity": true
  }
}

So we only need a way to distinguish Non-interactive blocks from Legacy Interactive blocks.

The main difference between them is that the Legacy Interactive blocks enqueue one or more JavaScript files that add interactivity in the frontend. The problem is that there is no way to detect that enqueue because it can happen practically at any moment and with any handle. It's true that the majority of these blocks will have a viewScript entry in their block.json, but that's not guaranteed.

If we can't reliably identify the Legacy Interactive blocks automatically, the only solution is to ask developers to declare something in their block.json. There are two options:

• Declare that a block is not compatible. In other words, declare that it is a Legacy Interactive block.
• Declare that a block is compatible. In other words, declare that it is a Non-Interactive block.

If we ask developers to declare blocks that are not compatible, we need to assume that all blocks that are not declared, are compatible. This obviously doesn't work because it will lead to false positives when a Legacy Interactive block is not declared yet.

So the only viable option is to declare blocks that are compatible: the Non-interactive blocks. That way, if a block compatibility is undeclared, we can treat it as not compatible. This will lead to false negatives, but that's ok because we are sure that no Legacy Interactive block will slip through.

At this moment I don't have any good ideas about how to do this declaration. The most obvious one would be to just set "supports.interactivity: false but it doesn't convince me, so please share your ideas about this.

If we do this, we would end up with:

{
  "supports": {
    "interactivity": true // Interactivity API block -> compatible
  }
}

{
  "supports": {
    "interactivity": false // Non-interactive block -> compatible
  }
}

{
  "supports": {
    // "interactivity" is missing:
    // Unkwnown block, it could be a Legacy Interactive block -> not compatible
  }
}

There's an edge case of a block that is not compatible with some features like region-based client-side navigation: a block that conditionally enqueues different CSS files depending on a certain server condition, so that should also be a requirement for compatibility.

If someone wants one of their Non-interactive blocks to work, they just need to declare it. And if someone wants one of their Legacy Interactive blocks to work, they just need to migrate it to the Interactivity API and then declare it. Blocks that are not registered on the server would also be treated as unknown. If someone wants them to work, they have to create a block.json first.

Now, for example, when someone tries to activate the enhanced pagination of the Query block, if all blocks that are inside the Post Template are compatible (they have supports.interactivity: true/false), the feature is activated without issues. If there's an unknown block, the user is notified that some specific block/s are incompatible, and the feature cannot be activated. If the feature is activated and the user introduces an unknown block in the Post Template, a message pops up saying that this block is not compatible and the feature has been deactivated.

If someone wants to create a block that always uses one of these features they can prevent users from adding not-compatible inner blocks in the Editor. That way, they will ensure that the features will always work and don't have to circumvent activating/deactivating the feature when a not-compatible block is added.

If we adopt this system, we could start declaring all the Core blocks, which means that all Core blocks would be safe to use in all these scenarios from the beginning, and in the vast majority of cases, blocks like the Query block will only contain Core blocks, so they will work fine. Then, we can start educating block developers so they start declaring their compatibility as well.

All in all, I'm not crazy about the idea that everyone has to state that their blocks are non-interactive/compatible in their block.json, but I can't think of another way of making all this automatic and we should prioritize the UX over the DX.

Please, let me know what you think.

cc: @mtias, @youknowriad, @oandregal, @mcsf, @gziolo, @jsnajdr, @DAreRodz, @SantosGuillamot, @dmsnell, @juanmaguitar, @ryanwelcher (feel free to ping other people)

[dmsnell]

Legacy Interactive blocks enqueue one or more JavaScript files that add interactivity in the frontend. The problem is that there is no way to detect that enqueue because it can happen practically at any moment and with any handle.

Not a fan of calling these "Legacy" since they don't represent an older generation of interactivity and in fact may be new and continue to live side-by-side with WordPress' interactive blocks. They could be part of broader component systems on large sites and the Interactivity API might simply not be a viable option for them.

That aside, is the problem that we are proposing to wipe out those blocks' rendered HTML from the server and try to render/hydrate them in the browser? I'm assuming those blocks would have no directives on them, so from our perspective, could it be that they are simply non-interactive?

What would break if we don't make this distinction?

[luisherranz]

Not a fan of calling these "Legacy"

I couldn't find a better name, sorry, but it's not my intention to use it outside of this discussion.

we are proposing to wipe out those blocks' rendered HTML from the server and try to render/hydrate them in the browser

No, no, don't worry. We're not proposing something new here, just a way to differentiate between compatible and non compatible blocks.

I'm assuming those blocks would have no directives on them, so from our perspective, could it be that they are simply non-interactive?

Both Non-interactive and Legacy Interactive blocks don't contain directives, so there's no way to distinguish between them using that.

[dmsnell]

Both Non-interactive and Legacy Interactive blocks don't contain directives, so there's no way to distinguish between them using that.

This was kind of where I was leading with my question: is there a difference? What is the problem that arises that makes us label externally-interactive blocks as legacy instead of simply "not-Interactivity-API"?

I know I'm still failing to understand what's happening here and that's leading to my confusion. Where I'm coming from is trying to understand this from the perspective of code trying to decide: "Do I need to do anything with this block when rendering or do I leave it alone?"

[luisherranz]

What is the problem that arises that makes us label externally-interactive blocks as legacy instead of simply "not-Interactivity-API"?

None really. At the time I wrote the post, it felt simpler to understand if I would use proper names than to use the longer versions Non Interactive, Interactive using the Interactivity API and Interactive not using the Interactivity API names to explain the issue, which is already quite complex to understand.

Again, this is only for the post and I don't plan to use the term Legacy outside of this discussion.

[priethor]

Thanks for the writeup, Luis. I was just talking with Pablo, and I pretty much agree with the way of declaring compatibility; it's the most obvious and direct one.

"interactivity": false // Non-interactive block -> compatible

However, I found this confusing at first and asked myself whether this should be not compatible instead. Although most incompatible blocks will not explicitly opt out and will just not declare the block supports, the way I read supports: { interactivity: false } is I don't support the interactivity API, which would be the default value when not declared.

On the other hand, non-interactive blocks will indeed be compatible and should specify interactivity: true. In my mind, this reads as I am compatible with the interactivity API, I support it, regardless of whether the block has some kind of interactivity or not.

[luisherranz]

You're right. But interactivity: true is still confusing if the block is not interactive, and we need a way to distinguish between those blocks as well.

So what about something like interactivity: "compatible" instead of interactivity: false?

[priethor]

Yeah, that was a second thought I had while typing, too 👍 . Moreover, adding an enum value would also open the door to different levels of compatibility.

[youknowriad]

Is the goal to make all blocks compatible or are there any use-cases where you think the block will never be compatible?

If it's the former, maybe we don't even need a new key and just use apiVersion: 4 like we did for iframe compatibility.

[luisherranz]

Is the goal to make all blocks compatible or are there any use-cases where you think the block will never be compatible?

There are blocks that use vanilla JS/jQuery for their interactivity whose developers might never want to migrate them to the Interactivity API. So, yes, there will be blocks that will never be compatible.

If it's the former, maybe we don't even need a new key and just use apiVersion: 4 like we did for iframe compatibility.

I thought about that and maybe it's something that we can do in the future if the Interactivity API is finally adopted as the standard. However, it feels less safe at this point as people with incompatible blocks may just update their block.json version from 3 to 4 and think that everything works fine when, in reality, they have just wrongly declared that their block is compatible with the Interactivity API.

[youknowriad]

it feels less safe at this point as people with incompatible blocks may just update their block.json version from 3 to 4 and think that everything works fine when, in reality, they have just wrongly declared that their block is compatible with the Interactivity API.

You could say the exact same thing about the iframe update and in that case, it's them doing it wrong. That said I'm more convinced about the argument that some jQuery based blocks might never upgrade.

[SantosGuillamot]

Thanks for the detailed explanation, Luis 🙂

I'm not a big fan of declaring compatibility in the non-interactive blocks, but I cannot think of a better system either.

Regarding the syntax, would it make sense to address the task to "Automatically detect interactive blocks" in the roadmap, and just have interactivity: "compatible" in the block.json? If we just have interactivity: "compatible" for both Interactivity API blocks and Non-Interactive blocks, and a mechanism to differentiate between them, it could look simpler.

[luisherranz]

That is a great idea, but I'm deviating a bit from the idea of automatically detecting interactive blocks. It made sense when we thought that the only difference between non-interactive and interactive blocks was the presence of directives. But now that we want to start adding configuration options to those blocks (like injecting the current namespace or hydration techniques), it makes sense to move them to the block.json and auto-inject it ourselves in the HTML from a DX point of view, and it making everything explicit makes our development much easier.

[SantosGuillamot]

Okay, that makes sense 🙂 Then I'm leaning towards the option of having interactiviy: true and interactivity: "compatible" (link), although it doesn't convince me 100%.

I'm not convinced about this either but, if we are going to have configuration options, would it make sense to have a siteWideFeatures/ compatibility property (with a better name)? It could be true by default if the interactivity object is defined, and false if it doesn't exist. Something like:

Interactive blocks

These use cases have the siteWideFeatures property true by default.

{
  "supports": {
    "interactivity": true
  }
}

{
  "supports": {
    "interactivity": {
      "namespace": "myPlugin"
    }
  }
}

{
  "supports": {
    "interactivity": {
      "load": {
        "view": {
          "rootMargin": "0px"
        }
      }
    }
  }
}

Non-interactive blocks

They have to declare it

{
  "supports": {
    "interactivity": {
      "siteWideFeatures": true
    }
  }
}

Legacy blocks

If supports.interactivity doesn't exist, it is false.

---

As I said, I am not convinced either. Just sharing in case it triggers other thoughts. It could be also transformed in the future into an array if we need to opt-in to some features and opt-out to others for any reason.

[luisherranz]

I like that 🙂

Although maybe with the siteWideFeatures property it feels like you are enabling those features instead of declaring compatibility with them.

What about just "compatible": true like this?

{
  "supports": {
    "interactivity": {
      "compatible": true
    }
  }
}

[SantosGuillamot]

You're right it seems you're enabling them. Although in a sense could be true. The other option I considered was using something like compatible, so that would be fine for me.

[ajgagnon]

IMO this is the way to go.

{
  "supports": {
    "interactivity": {
      "compatible": true
    }
  }
}

• It follows the standards that already exist for other parts of block.json (selectors, supports)
• It is more clear than true/false or enum.
• It keeps things flexible for future unknown interactivity options.

[luisherranz]

Another idea, more explicit, could be to use the term client-side navigation: "this block supports client-side navigation".

{
  "supports": {
    "clientSideNavigation": true
  }
}

Blocks made with the Interactivity API will be compatible by default.

I'm not sure if it's a good idea or not yet. It largely depends on what other things will need compatibility, and whether those things will follow the same rules as client-side navigation, or different rules. I'll try to think about it.

[luisherranz]

We're finally going with supports.interactivity.clientNavigation.

This is the related PR:

• Interactivity API: Add block supports for clientNavigation and interactive properties on block.json schema. #58132