HTML: IDL attributes and HTML attributes should be kept in sync

[LeaVerou]

This relates to #269.

In the future, we should avoid cases like <input value>, <option selected>, <input checked> etc, where the HTML attributes were never updated, and it was only the IDL attributes that reflected current state. This was incredibly confusing to teach, and the cause of a lot of buggy code.

Instead, the more recent trend has been to keep them in sync, e.g. <details open> is updated accordingly as HTMLDetailsElement#open is modified. I propose we ensure this trend continues by making it a design principle.

[LeaVerou]

@annevk @domenic we discussed this today and we wanted to get your feedback on this

The consensus on the call was that we do agree that they should be kept in sync to minimize developer pain and confusion, unless there is a good reason not to.

[domenic]

There's several subtleties here, but I agree with the general advice, and especially on the cases to avoid.

Some things that come to mind:

• All content attributes should have corresponding IDL attributes, but this relationship doesn't go the other way around. It's fine to have IDL attributes that don't have corresponding content attributes.

• Similarly, it's not 100% clear that the <details open=""> pattern is a success. This is more easily seen with <dialog open="">, where it's pretty broken. (We're trying to fix that in Dialog should be better-behaved on misuse, probably whatwg/html#5802 but even it's not clear whether the end result will be great.) In particular using attributes for this sort of thing requires that user interaction modify the DOM, which can be surprising for web developers (e.g. it plays poorly with some frameworks).

  My takeaway would be that using content attributes to control dynamic state is a bit fraught and should be thought about carefully. Whereas using IDL attributes or methods is relatively safe.

• As another example, I don't think the correct way of designing a "new" version of <input type="text" value=""> (call it <textbox value="">) would be to have an IDL value attribute stays in sync with the value="" content attribute, and have both of them be modified by user input. Instead it would probably be to change the API to <textbox defaultvalue=""> with a defaultValue IDL attribute, then have a value IDL attribute (with no corresponding content attribute) for the current value, which is modified by user input.

  • This is somewhat subjective, but I think I feel this way because having a string content attribute that gets updated as the user types seems more disruptive than having a boolean content attribute (like <details open="">) that gets updated on user interaction.

• Some related discussions: [Popup] Do we need the "open" content attribute? openui/open-ui#311 (comment), New indeterminate attribute for <input type=checkbox> whatwg/html#6578, and especially Discussion issue for attribute mappings tkent-google/std-switch#4 which goes into some of the form-control-specific subtleties such as interaction with resets.

[annevk]

The one thing I would add to the above is that modifying the node tree (as happens with <details>) creates the opportunity to run script due to mutation events, which presents its own set of challenges. (And might also be what surprises frameworks.)

But yeah, I definitely agree that naming the content attribute x and the IDL attribute defaultX was a mistake and the content attribute should have been named defaultx if we could do it again. (This might well have come about due to the early days mismatches in node tree implementations, come to think of it.)

[kenchris]

Could we say something like the following?

• All content attributes should have corresponding IDL attributes, but this relationship doesn't go the other way around. It's fine to have IDL attributes that don't have corresponding content attributes.
• Avoid adding content attributes for dynamic state, as that can involve firing events during parsing which is problematic, and requires keeping the attributes in sync. Instead consider adding a content attribute for initial or fallback values, like initiallyopen or defaultx.
• When content and IDL attributes represent the same thing, use the same name, potentially with a prefix for the content attribute, like initially (eg. initiallyopen) or default. Please follow the casing guidelines as they differ per IDL and content attributes

[LeaVerou]

@kenchris

As I wrote in #289 (comment) there is a lot of value in exposing state via (read/write) attributes, so I would be wary of introducing such guidance which prioritizes spec writers and implementors over authors ("Avoid adding content attributes for dynamic state"). Agreed with points 1 and 3.

[cynthia]

Also agree with points 1 and 3.

[kenchris]

I am still a bit worried about synching state when that involves firing events during parsing, or user input.

We could postpone these events till after finishing parsing, but then what about web components? Do it after elements are upgraded?

We already have issues with user input on the web today as people do processing on each key stroke instead of when the user is taking a small break, so additional processing will make this slightly worse

[LeaVerou]

Following today's breakout discussion, we can all agree that IFF an IDL property and an HTML attribute have the same name, then they should definitely be in sync and we should have a principle about this as violating this has caused a lot of confusion over the years. However, whether an IDL attribute should be reflected in an HTML attribute at all (which is what a lot of this discussion has centered around) is the subject of #289, not this issue.