Document declarative conventions and ensure alignment in existing components

[LeaVerou]

There are several components that support declarative commands, which we currently do ad hoc with data- attributes:

• data-toggle-nav on <wa-page>
• data-dialog="close" for <wa-dialog>

While we can't yet use the invoker API, it may be a good idea to use invoker-compatible syntax like command="--toggle-nav" so that we could seamlessly switch to it later. It costs us nothing and makes WA look forward-facing to those in the know (who are few, but tend to be influential). That said, I hate it that they went with the -- convention because it looks ugly AF. But that ship has sailed, and this syntax is where we're heading towards, so it could be argued that we may as well be the first to use it…

An alternative path could be to use our own command attribute, e.g. wa-command="toggle-nav" or wa-action="toggle-nav".

E.g. (if we go with data-wa-, which is a separate issue)

<button data-wa-action="toggle-nav">
<button data-wa-action="close-dialog">

WRT opening dialogs, idea by @claviska:

<button data-wa-action="open-dialog id">

<!-- OR, to use a selector -->
<button data-wa-action="open-dialog" data-wa-action-target="& + dialog">

Alternatively:

<button data-wa-action="open-dialog #id">

<!-- OR, to use a selector -->
<button data-wa-action="open-dialog & + dialog">

[claviska]

See the thread here regarding that API. https://bsky.app/profile/cory.laviska.com/post/3lb5oobabs22k

Specifically:

Is there a shortcut? I’m currently using data-dialog=“open id” and it would be more ergonomic to continue using one attribute.

command=“open:id”

or similar would be great.

I like a one-attribute approach over what we got, but here we are…

I do have a question about invokers that I'm still uncertain of. If we start using command and commandfor in our code, what happens when browsers finally support it? Will it fail gracefully, allowing custom elements to take over? Or will it throw a warning/error? 🤔

[LeaVerou]

See the thread here regarding that API. https://bsky.app/profile/cory.laviska.com/post/3lb5oobabs22k

Specifically:

Is there a shortcut? I’m currently using data-dialog=“open id” and it would be more ergonomic to continue using one attribute.
command=“open:id”
or similar would be great.

I like a one-attribute approach over what we got, but here we are…

I also hate that commandfor follows the established HTML pattern of idrefs which has terrible ergonomics, forcing authors to come up with ids for everything.
That said, ---prefixed commands can be anything, so in theory it could take the id as part of the command (e.g. command="--wa-open-dialog-foobar", but that looks kind of awful.

I do have a question about invokers that I'm still uncertain of. If we start using command and commandfor in our code, what happens when browsers finally support it? Will it fail gracefully, allowing custom elements to take over? Or will it throw a warning/error? 🤔

My understanding is that even when it's supported, as long as your action is -- prefixed all it will do is fire a command event (that you're supposed to handle to actually implement the action).

[LeaVerou]

The more I look at this, the more I think the -- is awful. However, I would love to have a consistent/extensible syntax to specify these commands, and also something that is clearly linked to WA.

What about a wa-command="toggle-nav" attribute? We could also support a data-wa-command version for anyone that is really keen on validating HTML.

[claviska]

data-dialog="open <id>" 🫠
data-dialog="close"

[LeaVerou]

Haaaa, came here to edit because I found data-dialog and I just saw your last comment! Yeah, let's unify these, do you agree?

[claviska]

data- prevents validation and type issues and it’s less to remember than invokers so I’m for it.

[LeaVerou]

data- prevents validation and type issues and it’s less to remember than invokers so I’m for it.

I opened #266 so we can discuss this more generally, since not all of these attributes are commands.