Differentiating between suffixes and unique-ids in the directive names

[luisherranz]

When attempting to augment an existing block with interactivity, all directives should include a unique-id to prevent collisions.

This is @westonruter from a conversation in Slack:

First of all, this is seeking to augment an existing block with interactivity.
[...]
I'm currently namespacing all of the directives I'm adding, along with adding suffixes to ensure uniqueness.

That means all directives should support unique-ids, maybe even by default.

As of today, only some directives support unique-ids but they use the same syntax as directives that use suffixes. For example:

• data-wp-on--click <- click is a suffix
• data-wp-watch--my-plugin <- my-plugin is a unique-id

So far, this has worked well.

What we've done in the directives with suffixes is to add the unique-ids at the end:

• data-wp-on--click--my-plugin

However, when the suffix is optional and we also want to add unique-ids, a conflict arises.

Imagine we want to add unique-ids to data-wp-class, but we also want it to be usable without a suffix (passing it an object of classes that can be true or false):

store('...', {
    state: {
        isRed: false,
        classes: {
            'is-bold': false,
            'is-blue': true
        }
    }
})

• data-wp-class--is-red="state.isRed" <- This works fine.
• data-wp-class="state.classes" <- This works fine.
• data-wp-class--my-plugin="state.classes" <- This doesn't work as expected, because my-plugin would be the name of the class (suffix), not the unique-id.

The same would happen if we want to use a suffix in data-wp-context to facilitate the writing of contexts with a single property:

• data-wp-context--is-open="false" <- This would be the equivalent of data-wp-context='{ "isOpen": false }'
• data-wp-context--my-plugin='{ "isOpen": false }' <- This won't work as expected because my-plugin would be the myPlugin property, not the unique-id.

So maybe we should standardize the syntax of the unique-ids and differentiate it from the suffixes.

The first idea that comes to mind is to use a triple dash: ---.

• data-wp-directive--suffix
• data-wp-directive---unique-id
• data-wp-directive--suffix---unique-id

So, there would no longer be a conflict to differentiate between suffix and unique-ids in directives where the suffix is optional:

• data-wp-class--is-red="state.isRed" <- This works fine.
• data-wp-class---my-plugin="state.classes" <- This works fine.
• data-wp-context--is-open="false" <- This works fine.
• data-wp-context---my-plugin='{ "isOpen": false }' <- This works fine.

We would need to check if we can make the change in a way that is backward compatible with the directives that are currently using unique-ids (and keep also the --), like:

• data-wp-watch--unique-id -> data-wp-watch---unique-id
• data-wp-init--unique-id -> data-wp-init---unique-id
• data-wp-on--suffix--unique-id -> data-wp-on--suffix---unique-id

---

Thoughts? Do you see any impediments? Any alternative syntax?

[sirreal]

It's a difficult task to put a lot of data into strings. There's risk of them becoming inscrutable or ambiguous. I do think a clear specification on exactly what the parts of directive attributes signify and how they'll be processed will be helpful for the Interactivity API and users.

If we're adding another part to the directive, why not use something other than more dashes? I don't think we're limited to just ascii lowercase and dashes, underscores and more characters should be perfectly fine. I looked at this recently:

---

A custom data attribute is an attribute in no namespace whose name starts with the string "data-", has at least one character after the hyphen, is XML-compatible, and contains no ASCII upper alphas.

(then)

Attribute names are said to be XML-compatible if they match the Name production defined in XML and they contain no U+003A COLON characters (:). [XML]

(finally):

Names and Tokens
[4]  NameStartChar ::= ":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | [#x370-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
[4a] NameChar      ::= NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
[5]  Name          ::= NameStartChar (NameChar)*
[6]  Names         ::= Name (#x20 Name)*
[7]  Nmtoken       ::= (NameChar)+
[8]  Nmtokens      ::= Nmtoken (#x20 Nmtoken)*

---

What about a different character like . for the namespace?

• data-wp-on--click.my-plugin
• data-wp-watch.my-plugin

https://core.trac.wordpress.org/ticket/61052 and WordPress/wordpress-develop#6429 contain some related work.

---

I'm worried that the term "namespace" is overloaded. Are these attached to Interactivity API store namespaces in some way? For many of the directives, their only purpose to to make the attributes unique, right? This might also be called a unique ID or key.

[SantosGuillamot]

This discussion we had back then might help with the different possibilities. It seems the other options considered were using a single hyphen, or using underscore.

The dot notation was used in the past, but it created issues with JSX.

[sirreal]

Oh, that's annoying! I was unaware, but found this issue and tested and you're absolutely correct.

Still, there are other characters that should be fine. # seems to be valid in JSX attributes and it has a nice association as the CSS selector ID prefix:

• data-wp-on--click#my-plugin
• data-wp-watch#my-plugin

[SantosGuillamot]

The other main consideration we had back then was using valid HTML characters. I remember using https://validator.w3.org/nu/#textarea to check it. For example, if I use the # character, it triggers some errors:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>New Tab</title>
</head>
<body>

<p data-wp-on--click#my-namespace="actions.myAction">My First Heading</p>

</body>
</html>

Anyway, it is an old discussion so maybe it can be revisited.

[luisherranz]

For many of the directives, their only purpose to to make the attributes unique, right? This might also be called a unique ID or key.

Good idea. Let's change the references from namespaces to unique-id for clarity. I'll edit the post.

Once we implement this, we can review the documentation and change it there as well.

[sirreal]

There's an important case to consider where style directives are used with CSS custom properties to get a suffix that starts with --:

data-wp-style----my-css-property="state.color"

We might wind up with -- suffix, --- unique-id, and ---- suffix+suffix value 👀

[luisherranz]

That's true, good catch.

In that case, we could use underscore (which is the other character allowed in HTML data attributes that also works in JSX), or make data-wp-class special and make it work as you mentioned: -- suffix, --- unique-id, and ---- suffix

[westonruter]

An alternative to having to add unique ID suffixes for all of the directives would be to allow the directive values to be comma-delimited. So instead of:

<div
  data-wp-on-click--foo="foo::actions.handleClick"
  data-wp-on-click--bar="bar::actions.handleClick"
>
</div>

It could instead be:

<div
  data-wp-on-click="foo::actions.handleClick, bar::actions.handleClick"
>
</div>

This is how AMP addressed the issue of associating multiple actions with a directive. For augmentation then, adding a new directive would be a matter of seeing if the directive already exists, and if so and then appending , followed by the new directive. For example:

$directives = $p->get_attribute( 'data-wp-on-click' );
if ( $directives ) {
    $directives .= ',';
} else {
    $directives = '';
}
$directives .= 'myPlugin::action.handleClick';
$p->set_attribute( 'data-wp-on-click', $directives );

or

$directives = $p->get_attribute( 'data-wp-on-click' ) . ',' . 'myPlugin::action.handleClick';
$p->set_attribute( 'data-wp-on-click', ltrim( $directives, ',' ) );

or

$directives = (array) $p->get_attribute( 'data-wp-on-click' );
$directives[] = 'myPlugin::action.handleClick';
$p->set_attribute( 'data-wp-on-click', implode( ', ', array_filter( $directives ) ) )

[luisherranz]

It is an interesting alternative. However, I'd like to be very careful with special syntax on directive values. After all, the value of the directives is not dictated by the framework, but by the directive. The fact that we only have directives whose values are either store/context references or JSON objects is temporary, and it would be especially relevant when we open the APIs to create custom directives.

<div
  data-wp-my-custom-directive="some value that might be anything the directive wants"
></div>

As of today, the only framework restriction on the directive value is that if it starts with a string (/[\w-_\/]+/) followed by ::, then that string doesn't belong to the directive value and it is extracted as the namespace (the directive doesn't even receive this namespace as part of the value).

Store/context references also capture a starting exclamation point ! that is applied as a negation. But that's part of the store/context reference evaluation provided by the evaluate function, not by the framework internals.

So for this to work, whatever syntax we use should be extracted by the framework and that syntax should be rarely found in a directive value, while being easy to parse and easy to remember by the devs at the same time.

It's also worth noting that the namespace and the unique-id are not exactly the same thing. One might want to add multiple directives for the same namespace, or don't use a namespace at all (use the default one).

Follwing the namespace syntax, one possiblity could be to use :: (with or without namespace), like:

<div
  data-wp-init="callbacks.doThis ::callbacks.doThat"
  data-wp-watch="foo::callbacks.doThis bar::callbacks.doThat"
  data-wp-context="{...} {...}"
></div>

The parser would split the items using something like / [\w-_\/]*::/.

In PHP, the logic of adding new items would be something like (following what Weston suggested here):

$directives = $p->get_attribute( 'data-wp-watch' ) . ' ::callbacks.doThat';
$p->set_attribute( 'data-wp-on-click', ltrim( $directives, ' ::' ) );

Although we could also accept the leading :: as valid:

<div data-wp-init=" ::callbacks.doThat" data-wp-context=" ::{...}"></div>

Which would simplify the PHP code to:

$directives = $p->get_attribute( 'data-wp-watch' ) . ' ::callbacks.doThat';
$p->set_attribute( 'data-wp-on-click', $directives );

But if we use this method, we'd have to assume that any text that contains / [\w-_\/]*::/ will cause parsing problems:

<div
  data-wp-context='{ "text": "This is going to break foo::bar badly" }'
></div>