IDREF attributes are fragile and painful to use

[LeaVerou]

(An earlier version of this was posted in whatwg/html#10143)

Pain points

Many HTML attributes need to reference one or more HTML elements in the document. This includes:

• for, in <label> and <output>
• list in <input>
• A host of ARIA attributes (e.g. aria-describedby, aria-labelledby, aria-activedescendant, aria-controls, aria-details, aria-flowto, aria-owns etc.)
• Popovers (popovertarget)
• Invokers (invoketarget)
• the new anchor attribute
• This is also a frequent need in author web components as well.

Currently, the only way to specify such references is to give these elements ids (if they don't already have them) and use these ids to link to them in these attributes.

This is problematic in several ways:

• Friction: It creates high friction for authoring HTML, especially when not using tooling to generate it. Authors then need to devise globally unique ids for elements that wouldn't otherwise have one and manually do the linking.
• Fragility: It introduces a host of error conditions. It is a common authoring mistake to change an id and forgetting to change the id references to it, pasting a chunk of HTML and forgetting to edit all the references, or ending up with broken references due to accidental duplicate ids.
• Inconsistency: We typically give web component authors the advice to follow HTML precedent. However in this case precedent has such poor ergonomics that WC authors have to invent their own referencing mechanisms, coming up with wildly inconsistent solutions because they are forced to choose between ergonomics and consistency with the web platform.
• Since ids are scoped to shadow trees, linking to elements across shadow boundaries is impossible. Cross-root ARIA is largely still an open question. There are many proposals, but all target it as an isolated problem and most involve high degrees of complexity.

This is a very common author pain point around ARIA, and authors are pretty vocal about it: DX-related complaints were the 3rd biggest a11y complaint in the preliminary State of HTML results. It especially hurts a11y, since the effects of broken references in the a11y tree are not always obvious, and the more effort it takes to make HTML accessible, the less likely authors are to do it. While for <label> this is somewhat mitigated by the option to make the association implicitly by nesting the form control within the <label>, for the other cases there is no similar option. New features like popovers, invokers, or the anchor attribute exacerbate the problem further.

The IDL attributes for these are also inconsistent:

• element.htmlFor returns a string, corresponding to the textual value of the for attribute. The actual element can be accessed via element.control.
• element.list returns the actual <datalist> element linked. The string value is only accessible via getAttribute().
• popoverTargetElement returns the element popovertarget corresponds to. The string value is only accessible via getAttribute().
• ariaDescribedByElements returns the elements aria-describedby corresponds to (and similar for other ARIA attributes). The string value is only accessible via getAttribute().

Potential solutions

• Being able to link to elements in a way that is relative to the element the attribute is specified on would solve most of these issues, and make writing ARIA much more pleasant. I’ve discussed several ideas here. A selector-based solution could potentially address some cross-root ARIA use cases too, as long as the element is exposed via part.
• Every element reference attribute should not just have an IDL attribute that reflects its value, but also an IDL attribute for getting/setting the referenced element(s).

Some considerations are:

• Backwards compat, if changing the syntax of existing attributes.
• The migration path for authors. It would introduce an undesirable cliff, if using a relative reference suddenly requires changing all of their existing absolute references. The more substantial the edit required, the sharper the cliff.
• Not all use cases require relative references, so ideally the syntax should allow mixing the two. While a11y-related use cases tend to primarily need relative references, attributes like list need both (e.g. a "country" field would need to autocomplete to the same list of countries everywhere).