Guidance about reflecting state in HTML attributes #501

LeaVerou · 2024-07-15T18:54:26Z

hober

Looks good to me.

hober · 2024-07-15T22:58:02Z

index.bs

@@ -1032,6 +1032,25 @@ The alternative user experience is a flash of unstyled content, which is undesir

 See also [[#worker-only]].

+<h3 id="html-attribute-property-reflection">Expose content attributes for writable IDL attributes</h3>
+
+When designing a new *writable* IDL attribute to specify element state,


The emphasis on "writable" doesn't seem to serve a purpose. (I, for one, find it distracting.)

I disagree, I think "writable" is essential to the principle and should be emphasized.

I would suggest a rephrase then.

When designing a new IDL attribute that reflects the state of an element,
expose a corresponding content attribute,
unless the attribute is immutable or
there are other strong reasons not to.

I'm also confused why "writable" matters here. Is there a reason immutable IDL attributes are less suitable to be reflected?

A lot of attributes are writable, which can make immutable attributes surprising.

index.bs

hober · 2024-07-15T23:00:37Z

index.bs

+- It takes advantage of HTML reactivity, and alleviates the need to apply changes at a specific moment in time.
+- It integrates with existing DOM methods, improving learnability, whereas an API specific to the feature needs to be learned separately.
+- Behaviors can be expressed reactively in libraries supporting HTML-based syntax and be handled by any library handling HTML generically.
+- UI states can be addressed in CSS via simple attribute selectors rather than new pseudo-classes.


I wonder if this is a good thing in all cases. For instance, [lang=foo] v. [lang|=foo] v. :lang(foo).

This seems orthogonal. In that case the pseudo-class serves a distinct purpose by targeting the actual computed language (which may be specified on an ancestor). I’d argue there may even be value in a generic attribute selector for these inherited attributes.

I'd favor Lea's point on this one. :lang() is justified because it is not as much about element state directly and more about the state of the DOM tree, as viewed from that node.

That said, the other point is also good: [lang=foo] is possible, but inadvisable.

hober · 2024-07-15T23:01:47Z

index.bs

+<{input}>'s  {{HTMLInputElement/indeterminate}} IDL property
+which was never exposed as a content attribute making it impossible to fully update checkbox state
+by modifying HTML.
+</div>


On the other hand, indeterminate is a terrible feature that should never have been added to the platform in the first place. Maybe we should try to find a more positive example?

Could you elaborate? Is it the UI of an indeterminate checkbox that you think is a mistake or the way it was added to HTML?

All of the above, IIRC.

The indeterminate IDL attribute is a bad example as it's like the checked or value IDL attributes which also do not have corresponding content attributes.

You could argue that we should have had a defaultIndeterminate IDL attribute for a corresponding indeterminate content attribute, but that's a separate matter. whatwg/html#6578 goes into this a bit.

(And of course people always like to point out that the IDL attributes not matching the names of the content attributes is confusing, but that's also a separate matter and anyway not something that can actually be solved.)

There’s a separate, existing, principle about this: Keep attributes in sync. It’s right below this one actually 😁

indeterminate in addition to that, also has no content attribute counterpart so there is no HTML way to specify it at all (current OR initial status).

@hober Interesting. Could you elaborate on the UI part?

That principle is about content attributes needing to be reflected right? But indeterminate is not a content attribute. Edit: ah right, it even says so in the note:

This does not hold the other way around. A new IDL attribute does not always warrant a content attribute counterpart.

Co-authored-by: Theresa O'Connor <[email protected]>

index.bs

hober · 2024-07-16T16:27:03Z

index.bs

+<{input}>'s  {{HTMLInputElement/indeterminate}} IDL property
+which was never exposed as a content attribute making it impossible to fully update checkbox state
+by modifying HTML.
+</div>


All of the above, IIRC.

martinthomson

I made this comment a VERY long time ago. I have not re-examined it for whether I still believe it.

martinthomson · 2024-08-21T07:58:03Z

index.bs

+- It takes advantage of HTML reactivity, and alleviates the need to apply changes at a specific moment in time.
+- It integrates with existing DOM methods, improving learnability, whereas an API specific to the feature needs to be learned separately.
+- Behaviors can be expressed reactively in libraries supporting HTML-based syntax and be handled by any library handling HTML generically.
+- UI states can be addressed in CSS via simple attribute selectors rather than new pseudo-classes.


I'd favor Lea's point on this one. :lang() is justified because it is not as much about element state directly and more about the state of the DOM tree, as viewed from that node.

That said, the other point is also good: [lang=foo] is possible, but inadvisable.

xiaochengh · 2025-04-17T09:14:10Z

I'll take a look

xiaochengh · 2025-04-28T10:18:27Z

Just a note that the original example <popup> in #289 is no longer there, and got replaced by the popover attribute. And popover visibility state is not exposed as content or IDL attributes, but only via CSS :popover-open selector.

annevk · 2025-04-28T11:08:01Z

To be clear, https://github.com/w3ctag/design-principles/pull/501/files#r1680595686 is still applicable. This should not be merged with the indeterminate example.

martinthomson · 2025-04-29T00:38:28Z

I'm not sure that I understand the concern about indeterminate. It seems like this could be made a content attribute (though what indeterminate + checked means is interesting to contemplate). The popover example might be similarly enlightening.

Basically, I think that our examples need to show where values are reflected as attributes in a good way (maybe; that's most of the platform, so it doesn't make sense to cherry pick one example) and where values were not reflected as attributes, to make the reasons for why that might be a good choice clear.

annevk · 2025-04-29T07:01:31Z

The concern is that the indeterminate IDL attribute is akin to the value IDL attribute, which doesn't have a content attribute counterpart. There's a value content attribute, but its IDL counterpart is defaultValue. So this suggestion makes it seem as if the TAG doesn't understand how HTML forms work. Which is reasonable as it's rather involved and essentially everybody gets confused about this, but adding to this confusion seems ill-advised.

martinthomson · 2025-04-29T23:59:59Z

To be clear, *I* don't understand how forms work; the use of pronoun should have made that clear. I'm just trying to shepherd this to a constructive conclusion.

@annevk, perhaps I can request that you offer an example that would help illustrate this principle. Or, maybe you would prefer that we not pursue this further. Explaining why would be helpful.

annevk · 2025-04-30T06:39:52Z

Can you clarify what part about my value example is unclear?

martinthomson · 2025-04-30T10:26:46Z

Ah, I hadn't interpreted that as a suggestion for a better example. Indeed, I would be OK switching to value and defaultValue in the example.

annevk · 2025-04-30T12:10:28Z

Oh my bad, I had in fact misunderstood your question.

I'm actually not sure the HTML community is fully aligned on this principle. While some state certainly deserves to be reflected through a content attribute, that does not go for state that is the result of end user input.

The open content attribute of the dialog and details elements is designed to always reflect the current state of the control, but this has resulted in a number of subtle issues and also seems to go against expectations. Web developers don't expect node tree mutations as the result of end users manipulating a control. We also have to be very careful to not re-introduce mutation events if we want to make these state changes observable to web developers.

cc @smaug---- @lukewarlow

lukewarlow · 2025-04-30T12:30:16Z

I do agree that IDL attributes should generally reflect to HTML content attributes. And that the names should match up (value attribute should be defaultvalue imo).

Being able to represent initial state via HTML is good. Indeterminate is an example where we can't currently do that.

The specific point about targeting attributes rather than pseudo-classes seems wrong though. The open attribute is a design mistake and even that we now have the :open pseudo class to target instead of using [open]. Custom elements can similarly follow this pattern using CSS custom states.

Also suggesting that reflecting IDL to HTML content attributes allows for this isn't quite right either, because internal element state that's changed via interaction (other than for open) doesn't reflect to the attribute and so you'd still need a CSS way to access that state.

This note seems to be over reaching slightly.

The note about reactive html also seems potentially wrong depending on if I'm reading it right. The open attribute is reactive and even that doesn't work if your library is setup to act on the attribute (or property, tbf so perhaps not a great example?)

First stab at #289

de81d1d

LeaVerou requested review from hober and martinthomson July 15, 2024 18:54

hober approved these changes Jul 15, 2024

View reviewed changes

Update index.bs

c599e4b

Co-authored-by: Theresa O'Connor <[email protected]>

hober approved these changes Jul 16, 2024

View reviewed changes

Update index.bs

039c7ef

martinthomson reviewed Dec 3, 2024

View reviewed changes

martinthomson changed the title ~~First stab at #289~~ Guidance about reflecting state in HTML attributes Dec 3, 2024

torgo added this to the 2025-02-10-week milestone Feb 9, 2025

jyasskin self-requested a review February 18, 2025 23:50

jyasskin assigned xiaochengh and martinthomson Apr 22, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Guidance about reflecting state in HTML attributes #501

Guidance about reflecting state in HTML attributes #501

LeaVerou commented Jul 15, 2024 •

edited by pr-preview bot

Loading

hober left a comment

hober Jul 15, 2024

LeaVerou Jul 15, 2024

martinthomson Aug 21, 2024

xiaochengh Apr 28, 2025

martinthomson Apr 29, 2025

hober Jul 15, 2024

LeaVerou Jul 15, 2024

martinthomson Aug 21, 2024

hober Jul 15, 2024

LeaVerou Jul 15, 2024

hober Jul 16, 2024

annevk Jul 17, 2024 •

edited

Loading

LeaVerou Jul 17, 2024 •

edited

Loading

LeaVerou Jul 17, 2024

annevk Aug 21, 2024 •

edited

Loading

hober Jul 16, 2024

martinthomson left a comment

martinthomson Aug 21, 2024

xiaochengh commented Apr 17, 2025

xiaochengh commented Apr 28, 2025

annevk commented Apr 28, 2025

martinthomson commented Apr 29, 2025

annevk commented Apr 29, 2025

martinthomson commented Apr 29, 2025

annevk commented Apr 30, 2025

martinthomson commented Apr 30, 2025

annevk commented Apr 30, 2025

lukewarlow commented Apr 30, 2025

Guidance about reflecting state in HTML attributes #501

Are you sure you want to change the base?

Guidance about reflecting state in HTML attributes #501

Conversation

LeaVerou commented Jul 15, 2024 • edited by pr-preview bot Loading

hober left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annevk Jul 17, 2024 • edited Loading

Choose a reason for hiding this comment

LeaVerou Jul 17, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annevk Aug 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martinthomson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xiaochengh commented Apr 17, 2025

xiaochengh commented Apr 28, 2025

annevk commented Apr 28, 2025

martinthomson commented Apr 29, 2025

annevk commented Apr 29, 2025

martinthomson commented Apr 29, 2025

annevk commented Apr 30, 2025

martinthomson commented Apr 30, 2025

annevk commented Apr 30, 2025

lukewarlow commented Apr 30, 2025

LeaVerou commented Jul 15, 2024 •

edited by pr-preview bot

Loading

annevk Jul 17, 2024 •

edited

Loading

LeaVerou Jul 17, 2024 •

edited

Loading

annevk Aug 21, 2024 •

edited

Loading