Document accesskit properties and roles that don't match ARIA

[PoignardAzur]

Accesskit types are ported for chromium's API, which don't always match ARIA properties.

I've gone through the entire property list with @DataTriny and we wrote the mismatched properties, though my notes are sparse and I usually didn't note what the exact mismatch was. Still, if we want to document our relationship with ARIA, these properties are a good starting point:

• IsSpellingError
• IsGrammarError
• IsSearchMatch
• IsSuggestion
• Children
• InPageLinkTarget
• MemberOf
• NextOnLine
• PreviousOnLine
• PopupFor
• Label
• Value
• ClassName
• HtmlTag
• Url
• RowIndexText
• ColumnIndexText
• ScrollX
• ScrollXMin
• ScrollXMax
• ScrollY
• ScrollYMin
• ScrollYMax
• NumericValue
• NumericValueStep
• NumericValueJump
• FontSize
• FontWeight
• BackgroundColor
• ForegroundColor
• Overline
• Strikethrough
• Underline
• Invalid
• Toggled
• TextDirection
• ListStyle
• TextAlign
• VerticalOffset
• TextSelection

Ideally we should also document differences in roles and actions, but I haven't started to list those.

[PoignardAzur]

Some additional notes:

• Some properties are one-indexed in ARIA and zero-indexed in AccessKit, such as RowIndex, ColumnIndex, Level, and PositionInSet.
• Label is equivalent to name in ARIA.
• Value is somewhat equivalent to valuetext in ARIA.
• NumericValue is equivalent to valuenow in ARIA.
• MinNumericValue is equivalent to valuemin in ARIA.
• MaxNumericValue is equivalent to valuemax in ARIA.
• Toggled is somewhat equivalent to either checked or pressed in ARIA.

[blinding-pixels]

I would be happy to start on this. I think maybe starting with a bounded scope on a smaller subsection could be good. That way we can nail down the format, language and tone?

I want to make sure I understand correctly: for each AccessKit role, property, etc., we want to explain what it means, link to its equivalent ARIA item if one exists, and note any differences from the ARIA version?

Putting down an example below as per my current understanding.

Role::Button

AccessKit definition

Role::Button represents a control that performs an action when activated. The node should normally have an accessible label and support Action::Click.

ARIA equivalent

A button is a control that allows users to trigger an action, such as submitting a form, opening a dialog, or cancelling an operation.

ARIA reference: WAI-ARIA button role

Differences and notes

AccessKit provides the button's accessibility semantics but does not implement keyboard, pointer, focus, or activation behavior. The application must handle those interactions and respond to Action::Click.

Example

let mut button = Node::new(Role::Button);
button.set_label("Apply");
button.add_action(Action::Click);

[PoignardAzur]

To be clear, the kind of documentation I'm thinking of is inline doc that shows up on docs.rs, not a standalone file. We're not planning to write a spec yet. And outside of a spec, we really, really don't want this level of verbosity, otherwise the Role enum documentation is going to be a text wall.

I think the ideal doc would be one line per role/property:

Role::Button represents a control that performs an action when activated. The node should normally have an accessible label and support Action::Click. ARIA equivalent: WAI-ARIA button role.

We could also add another line for differences:

Role::Button represents a control that performs an action when activated. The node should normally have an accessible label and support Action::Click. ARIA equivalent: WAI-ARIA button role.

Difference with ARIA: Unlike ARIA where X must be Y, in AccessKit X must instead be Z.

In the case of Button, there are no differences to specify. The fact that AccessKit doesn't implement UI behavior for user interactions isn't specific to Button, it's the same for all possible roles, so we shouldn't specify it for a role's doc.

[DataTriny]

Also when we talk about properties, this doesn't include the role. Roles are a different beast and documenting them would be a separate project. Properties are basically all other getters on the accesskit::Node type, as Olivier listed in the description of this issue.

[blinding-pixels]

Understood. Before I proceed, I want to clarify the intended scope.

I was referring to [this comment in #743](#743 (comment)), which suggests documenting the ARIA correspondence for both roles and properties. I see that this issue specifically concerns AccessKit properties that do not directly match ARIA.

Would you prefer that I identify and document the differences within a specific set of properties, or explore the broader documentation effort correlating AccessKit roles and properties with their ARIA equivalents?

For example, the inline documentation for Role::Button could be:

/// Represents a control that performs an action when activated. The node should
/// normally have an accessible label and support [`Action::Click`]. ARIA
/// equivalent: [WAI-ARIA button role](https://www.w3.org/TR/wai-aria-1.2/#button).
Button,

[PoignardAzur]

I edited this issue to expand the scope, to keep the discussion simpler. I do think we need to address both properties and roles, but I haven't looked at roles yet.

[blinding-pixels]

I could start with the properties maybe with a sub set as a small PR. Something easy to review, and if it works then I can expand it out further. Was that above Rust example closer to what you are looking for?

[DataTriny]

@blinding-pixels Yes, you could kickstart the project like this. The best way to keep a manageable scope would be to tackle all the properties with the same type. For instance you could start with the string properties:

accesskit/common/src/lib.rs

Line 1911 in c88605b

string_property_methods! {

[blinding-pixels]

Great, on it.