Add ARIA attribute typings

[andrewiggins]

Describe the feature you'd love to see

React typings have ARIA attributes defined providing stronger typing for the expected values of aria attributes. I think it'd be nice if we provided something similar, give people using TypeScript or people writing JS in an editor that uses TS for completions a nicer experience.

Additional context (optional)
Here is an example of the kind of feedback TypeScript can provide with proper aria typings.
https://www.typescriptlang.org/play?ts=4.9.4#code/JYWwDg9gTgLgBAJQKYEMDG8BmUIjgIilQ3wG4AoNCAOwGd4ATOAXjgB4HgA3OFKYFAFoUAVxgQq4ADZIYSZvloMpmfHAD0APlJA

Perhaps worth exploring if we can reuse anything from TypeScript's lib.dom.d.ts assuming it's typings match what we do.

[myasonik]

Anything would be better than nothing of course but for whoever ends up looking at this, a few more thoughts on this:

lib.dom implements the weakest types where everything is an optional string. That's technically correct and will prevent issues like folks misspelling aria attributes and whatnot but is quite limited.

React goes one step further and validates the values a little more expecting things like booleans and explicit enums where appropriate. This has the added benefit of validating correct key-value pairs which might be correct HTML but isn't always a correct use of ARIA.

Most ARIA attributes need to be on specific HTML elements (or elements with a specific role).
And many attributes should never be used together. This would probably be stricter than many other things are typed but because of a general lack of developer education and testing of assistive tech, I think it would be really valuable here. Using aria-autocomplete as a nice short example: it should only ever be used on HTML elements that either implicitly or explicitly have the roles of combobox, textbox, searchbox.

I know getting the typings that strict would be a lot more work but it could be a big win for both developer education and accessible software.

[nathonius]

Accessibility is super important in general, but this gap in preact's types is one of the reasons I can't yet make the case to switch my employer to preact. We have commitments to hit WCAG AA compliance, which in many cases requires the use of aria attributes, and with a big distributed team accurate types are a must.

However, even though I'd love to see this tomorrow with any/unknown types just to avoid having to {'aria-label': 'accessible text'} as any a prop type, I have to agree with @myasonik that it would definitely be better to have strict types; bad aria is usually worse than no aria. Though I'm not sure if it's really preact's job to enforce that.

[andrewiggins]

lib.dom implements the weakest types where everything is an optional string. ... React goes one step further and validates the values a little more expecting things like booleans and explicit enums where appropriate.

Oh good call! Yea, I've copied what React does here to provide better typings for values using enums and booleans where possible as a start in #3910.

Most ARIA attributes need to be on specific HTML elements (or elements with a specific role).
And many attributes should never be used together. ... but it could be a big win for both developer education and accessible software.

Agreed! This would be a great feature add. I'm not familiar enough with the right combinations to get this right, but would be open to other experts weighing in here on what the correct combos are for this. Also not entirely sure how to effectively type this in TypeScript in a non-breaking way. Would probably involve a decent amount of type unions and intersections would be my guess.

[myasonik]

Leaving this here in case someone wants to pick the typescript side of this: A project called aria-query might help someone unfamiliar with aria figure out the correct type behavior without having to dig through the spec. It will spit out all the valid pairings, required attributes, etc.

I'm not sure what the maximum possible implementation is of ARIA in TS because some things would require pretty complicated conditionals (including what the rendered element is) but it's almost certainly further than what is implemented today.

Ultimately, the most complete solution will likely need to be in something like eslint with the TS parser but that's a whole other can of worms. So I think implementing what parts we can, where we can, is the best approach.

For anyone looking at this and feeling overwhelmed: even going through one role or attribute and either strengthening those types or documenting that it can't be further strengthened would be really valuable. This does not need to be an all or nothing effort.