Clarify how to use reflect in a specification #8980
Conversation
annevk
added
clarification
| @@ -8410,6 +8396,34 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute | |||
| type are strongly encouraged to have their identifier end in "<code data-x="">Elements</code>" for | |||
| consistency.</p> | |||
|
|
|||
| <h4>Using reflect in specifications</h4> | |||
|
|
|||
| <p>The <span>reflect</span> functionality is primarily about improving web developer ergonomics by | |||
There was a problem hiding this comment.
Here would be my attempt:
Reflection is primarily about improving web developer ergonomics by giving them typed access to content attributes through reflected IDL attributes. The ultimate source of truth, which the rest of the web platform specification ecosystem interacts with, is still the content attributes themselves. That is, specification authors must not use the reflected IDL attribute's getter or setter steps, but instead must use the content attribute's presence and value. (Or some appropriate abstraction on top of it, such as the current state of an [enumerated attribute].)
There was a problem hiding this comment.
Thanks, I used a lot from this.
| <code>Element</code> or an interface that inherits from <code>Element</code></li> | ||
| </ul> | ||
|
|
||
| <p>For those, specification authors are to exclusively build upon the <span>reflected |
There was a problem hiding this comment.
My attempt:
For content attributes which have such reflected IDL attributes, specification authors must instead use the reflected target's attr-associated element or attr-associated elements respectively. The content attribute values themselves must not be used, as they can contain values that are out of sync with what the web developer has set via the reflected IDL attributes.
Not sure how happy I am with this exact text, but I wanted to clarify this.
/common-dom-interfaces.html ( diff )
/index.html ( diff )