feat: support children presentational property on roles

[cmorten]

Proposal

Summary

The WAI-ARIA spec defines for each role whether children of said role are considered presentational.

This request is to extend the current roles interface with this additional Boolean from the spec.

Detail

See https://www.w3.org/TR/wai-aria-1.3/#childrenArePresentational for the explanation.

See https://www.w3.org/TR/wai-aria-1.3/#img as an example of a role with presentational children.

Expect would extend the current RoleData interface at https://github.com/drwpow/html-aria/blob/main/src/lib/aria-roles.ts#L15.

Example

A commonish example is when writing custom images with aria:

    <!-- 3. In the following code sample, the containing img and is appropriately labeled by the caption paragraph. In this example the img element can be marked as presentation because the role and the text alternatives are provided by the containing element. -->
    <div role="img" aria-labelledby="caption">
      <img src="example.png" role="presentation" alt="">
      <p id="caption">A visible text caption labeling the image.</p>
    </div>

(Taken from WPT test suite, citation needed)

Consumers of this library would benefit from the new property as it would help inform that they should consider the children of the div with the img role as presentational, and therefore that they should not be considered by user agents / ATs etc.

Tradeoffs / breaking changes

This would introduce additional maintenance overhead.

It would also slightly counter the tenet that only MUST requirements are adhered to for this library - though as a counter, the addition is to reflect the spec, it would be on downstream consumers to decide if they consume and adhere to the property value/purpose.

Alternatives considered

Continue to use aria-query or an alternative library for this data.

[drwpow]

Would hasPresentationalChildren(element) be a useful API for this?

Somewhat suggested by #25, I’m thinking that deep traversal would just only be supported if passing in an actual element, in a DOM-like environment (i.e. this would throw an error when only passing in an object element)

Just as a larger question, many roles (trees, menus, etc) do require specific hierarchies. Would hasPresentationalChildren() be used with a hasValidChildren(element) method if it were to exist? My reading of the “SHOULD” language here seems to suggest it wouldn’t—it’s not technically invalid, just a recommendation.

[cmorten]

Would hasPresentationalChildren(element) be a useful API for this?

Not sure… something about it feels ambiguous as to whether children have a (implicit or explicit) presentational role, whereas the intent is to understand if this current element has a role such that children should be considered/made/assumed presentational…

I think this need only act on role rather than an element as it is a property of the role rather than the element itself (though they are somewhat interchangeable in one being inherited from the other)

Not sure what a better alternative would be…

• areChildrenPresentational(role)
• getAreChildrenPresentational(role)
• getChildrenArePresentational(role)
• shouldChildrenBePresentational(role)

Though feel a bit clunky?

[drwpow]

Hm yeah originally I just skipped all the “SHOULD”s and stuck with “MUST”s because the lint rules I was writing needed black-and-white errors and not so much loose warnings, if that makes sense.

I could see 2 approaches here that might address this and related issues:

1. rename the syntax to include should/recommended vs must/required language, e.g. shouldHavePresentationalChildren(). But that might rub up against the library’s goal of preventing mistakes with methods, such as someone needing to query getRequiredAriaAttributes() getRecommendedAriaAttributes() together. Which is less ergonomic and IMO requiring people to know to call multiple methods together is a bad design pattern
2. Change the return shape to be more verbose for the sake of clarity. For example, getSupportedAriaAttributes() could just become getAriaAttributes() that returns a map of required, optional, forbidden, etc. For things like the original issue of presentational children, perhaps getRole() returned the relevant info that maps to the spec rather than just a string. Then you could see childrenPresentational.

I’m leaning toward the latter, so long as we still keep the “MUST” information obvious. And we include the “SHOULD” information in perhaps a more ambiguous way and leave it up to the consumer to have the knowledge to know how to use it (such as yourself).

Does that sound reasonable? (Sorry for the side-tangent, just wanted to think about this holistically)