Skip to content

feat(lint/html): implement useValidAriaRole for html #8307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ematipico merged 1 commit into from
Dec 4, 2025
Merged

feat(lint/html): implement useValidAriaRole for html #8307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/lucky-snails-happen.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@biomejs/biome": minor
---

Added the `useValidAriaRole` lint rule for HTML. The rule enforces that elements with ARIA roles must use a valid, non-abstract ARIA role.
1 change: 1 addition & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions crates/biome_html_analyze/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ version = "0.5.7"

[dependencies]
biome_analyze = { workspace = true }
biome_aria_metadata = { workspace = true }
biome_console = { workspace = true }
biome_deserialize = { workspace = true }
biome_deserialize_macros = { workspace = true }
Expand Down
3 changes: 2 additions & 1 deletion crates/biome_html_analyze/src/lint/a11y.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,5 @@ pub mod no_header_scope;
pub mod use_button_type;
pub mod use_html_lang;
pub mod use_iframe_title;
declare_lint_group! { pub A11y { name : "a11y" , rules : [self :: no_access_key :: NoAccessKey , self :: no_distracting_elements :: NoDistractingElements , self :: no_header_scope :: NoHeaderScope , self :: use_button_type :: UseButtonType , self :: use_html_lang :: UseHtmlLang , self :: use_iframe_title :: UseIframeTitle ,] } }
pub mod use_valid_aria_role;
declare_lint_group! { pub A11y { name : "a11y" , rules : [self :: no_access_key :: NoAccessKey , self :: no_distracting_elements :: NoDistractingElements , self :: no_header_scope :: NoHeaderScope , self :: use_button_type :: UseButtonType , self :: use_html_lang :: UseHtmlLang , self :: use_iframe_title :: UseIframeTitle , self :: use_valid_aria_role :: UseValidAriaRole ,] } }
149 changes: 149 additions & 0 deletions crates/biome_html_analyze/src/lint/a11y/use_valid_aria_role.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
use biome_analyze::{
Ast, FixKind, Rule, RuleDiagnostic, RuleSource, context::RuleContext, declare_lint_rule,
};
use biome_aria_metadata::AriaRole;
use biome_console::markup;
use biome_diagnostics::Severity;
use biome_html_syntax::AnyHtmlElement;
use biome_rowan::{AstNode, BatchMutationExt};
use biome_rule_options::use_valid_aria_role::UseValidAriaRoleOptions;

use crate::HtmlRuleAction;

declare_lint_rule! {
/// Elements with ARIA roles must use a valid, non-abstract ARIA role.
///
/// Remember that this rule only supports static values for the `role` attribute.
/// Dynamic `role` values are not checked.
///
/// ## Examples
///
/// ### Invalid
///
/// ```html,expect_diagnostic
/// <div role="datepicker"></div>
/// ```
///
/// ```html,expect_diagnostic
/// <div role="range"></div>
/// ```
///
/// ```html,expect_diagnostic
/// <div role=""></div>
/// ```
///
///
/// ### Valid
///
/// ```html
/// <div role="button"></div>
/// <div></div>
/// ```
///
/// ## Options
///
///
/// ### `allowInvalidRoles`
///
/// It allows specifying a list of roles that might be invalid otherwise
///
/// ```json,options
/// {
/// "options": {
/// "allowInvalidRoles": ["datepicker"]
/// }
/// }
/// ```
///
/// ```html,use_options
/// <div role="datepicker"></div>
/// ```
///
/// ## Accessibility guidelines
///
/// - [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
///
/// ## Resources
///
/// - [Chrome Audit Rules, AX_ARIA_01](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_01)
/// - [DPUB-ARIA roles](https://www.w3.org/TR/dpub-aria-1.0/)
/// - [MDN: Using ARIA: Roles, states, and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques)
///
pub UseValidAriaRole {
version: "next",
name: "useValidAriaRole",
language: "html",
sources: &[RuleSource::EslintJsxA11y("aria-role").same()],
recommended: true,
severity: Severity::Error,
fix_kind: FixKind::Unsafe,
}
}

impl Rule for UseValidAriaRole {
type Query = Ast<AnyHtmlElement>;
type State = ();
type Signals = Option<Self::State>;
type Options = UseValidAriaRoleOptions;

fn run(ctx: &RuleContext<Self>) -> Self::Signals {
let node = ctx.query();
let options = ctx.options();

let allowed_invalid_roles = &options.allow_invalid_roles;

let role_attribute = node.find_attribute_by_name("role")?;
let role_attribute_static_value =
role_attribute.initializer()?.value().ok()?.string_value()?;
let role_attribute_value = role_attribute_static_value.trim();
if role_attribute_value.is_empty() {
return Some(());
}
let mut role_attribute_value = role_attribute_value.split_ascii_whitespace();

let is_valid = role_attribute_value.all(|val| {
AriaRole::from_roles(val).is_some()
|| allowed_invalid_roles
.iter()
.flatten()
.any(|role| role.as_ref() == val)
});

if is_valid {
return None;
}

Some(())
}

fn diagnostic(ctx: &RuleContext<Self>, _: &Self::State) -> Option<RuleDiagnostic> {
let node = ctx.query();
Some(
RuleDiagnostic::new(
rule_category!(),
node.range(),
markup! {
"Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role."
},
)
.note(markup! {
"Check "<Hyperlink href="https://www.w3.org/TR/wai-aria/#namefromauthor">"WAI-ARIA"</Hyperlink>" for valid roles or provide options accordingly."
})
)
}

fn action(ctx: &RuleContext<Self>, _: &Self::State) -> Option<HtmlRuleAction> {
let node = ctx.query();
let mut mutation = ctx.root().begin();
let role_attribute = node.find_attribute_by_name("role")?;
mutation.remove_node(role_attribute);
Some(HtmlRuleAction::new(
ctx.metadata().action_category(ctx.category(), ctx.group()),
ctx.metadata().applicability(),

markup! { "Remove the invalid "<Emphasis>"role"</Emphasis>" attribute.\n Check the list of all "<Hyperlink href="https://www.w3.org/TR/wai-aria/#role_definitions">"valid"</Hyperlink>" role attributes." }
.to_owned(),
mutation,
))
}
}
2 changes: 2 additions & 0 deletions crates/biome_html_analyze/tests/specs/a11y/useValidAriaRole/allowInvalidRoles.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<!-- should not generate diagnostics -->
<div role="datepicker"></div>
10 changes: 10 additions & 0 deletions crates/biome_html_analyze/tests/specs/a11y/useValidAriaRole/allowInvalidRoles.html.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
source: crates/biome_html_analyze/tests/spec_tests.rs
expression: allowInvalidRoles.html
---
# Input
```html
<!-- should not generate diagnostics -->
<div role="datepicker"></div>

```
15 changes: 15 additions & 0 deletions crates/biome_html_analyze/tests/specs/a11y/useValidAriaRole/allowInvalidRoles.options.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"$schema": "../../../../../../packages/@biomejs/biome/configuration_schema.json",
"linter": {
"rules": {
"a11y": {
"useValidAriaRole": {
"level": "error",
"options": {
"allowInvalidRoles": ["datepicker"]
}
}
}
}
}
}
8 changes: 8 additions & 0 deletions crates/biome_html_analyze/tests/specs/a11y/useValidAriaRole/invalid.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<!-- should generate diagnostics -->
<div role="range"></div>
<div role="datepicker"></div>
<div role=""></div>
<div role="datepicker" />
<div role="unknown-invalid-role" />
<div role="tabpanel row foobar"></div>
<div role="doc-endnotes range"></div>
169 changes: 169 additions & 0 deletions crates/biome_html_analyze/tests/specs/a11y/useValidAriaRole/invalid.html.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
---
source: crates/biome_html_analyze/tests/spec_tests.rs
expression: invalid.html
---
# Input
```html
<!-- should generate diagnostics -->
<div role="range"></div>
<div role="datepicker"></div>
<div role=""></div>
<div role="datepicker" />
<div role="unknown-invalid-role" />
<div role="tabpanel row foobar"></div>
<div role="doc-endnotes range"></div>

```

# Diagnostics
```
invalid.html:2:1 lint/a11y/useValidAriaRole FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.

1 │ <!-- should generate diagnostics -->
> 2 │ <div role="range"></div>
│ ^^^^^^^^^^^^^^^^^^^^^^^^
3 │ <div role="datepicker"></div>
4 │ <div role=""></div>

i Check WAI-ARIA for valid roles or provide options accordingly.

i Unsafe fix: Remove the invalid role attribute.
Check the list of all valid role attributes.

2 │ <div·role="range"></div>
│ ------------

```

```
invalid.html:3:1 lint/a11y/useValidAriaRole FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.

1 │ <!-- should generate diagnostics -->
2 │ <div role="range"></div>
> 3 │ <div role="datepicker"></div>
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4 │ <div role=""></div>
5 │ <div role="datepicker" />

i Check WAI-ARIA for valid roles or provide options accordingly.

i Unsafe fix: Remove the invalid role attribute.
Check the list of all valid role attributes.

3 │ <div·role="datepicker"></div>
│ -----------------

```

```
invalid.html:4:1 lint/a11y/useValidAriaRole FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.

2 │ <div role="range"></div>
3 │ <div role="datepicker"></div>
> 4 │ <div role=""></div>
│ ^^^^^^^^^^^^^^^^^^^
5 │ <div role="datepicker" />
6 │ <div role="unknown-invalid-role" />

i Check WAI-ARIA for valid roles or provide options accordingly.

i Unsafe fix: Remove the invalid role attribute.
Check the list of all valid role attributes.

4 │ <div·role=""></div>
│ -------

```

```
invalid.html:5:1 lint/a11y/useValidAriaRole FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.

3 │ <div role="datepicker"></div>
4 │ <div role=""></div>
> 5 │ <div role="datepicker" />
│ ^^^^^^^^^^^^^^^^^^^^^^^^^
6 │ <div role="unknown-invalid-role" />
7 │ <div role="tabpanel row foobar"></div>

i Check WAI-ARIA for valid roles or provide options accordingly.

i Unsafe fix: Remove the invalid role attribute.
Check the list of all valid role attributes.

5 │ <div·role="datepicker"·/>
│ ------------------

```

```
invalid.html:6:1 lint/a11y/useValidAriaRole FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.

4 │ <div role=""></div>
5 │ <div role="datepicker" />
> 6 │ <div role="unknown-invalid-role" />
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7 │ <div role="tabpanel row foobar"></div>
8 │ <div role="doc-endnotes range"></div>

i Check WAI-ARIA for valid roles or provide options accordingly.

i Unsafe fix: Remove the invalid role attribute.
Check the list of all valid role attributes.

6 │ <div·role="unknown-invalid-role"·/>
│ ----------------------------

```

```
invalid.html:7:1 lint/a11y/useValidAriaRole FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.

5 │ <div role="datepicker" />
6 │ <div role="unknown-invalid-role" />
> 7 │ <div role="tabpanel row foobar"></div>
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8 │ <div role="doc-endnotes range"></div>
9 │

i Check WAI-ARIA for valid roles or provide options accordingly.

i Unsafe fix: Remove the invalid role attribute.
Check the list of all valid role attributes.

7 │ <div·role="tabpanel·row·foobar"></div>
│ --------------------------

```

```
invalid.html:8:1 lint/a11y/useValidAriaRole FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.

6 │ <div role="unknown-invalid-role" />
7 │ <div role="tabpanel row foobar"></div>
> 8 │ <div role="doc-endnotes range"></div>
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9 │

i Check WAI-ARIA for valid roles or provide options accordingly.

i Unsafe fix: Remove the invalid role attribute.
Check the list of all valid role attributes.

8 │ <div·role="doc-endnotes·range"></div>
│ -------------------------

```
10 changes: 10 additions & 0 deletions crates/biome_html_analyze/tests/specs/a11y/useValidAriaRole/valid.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<!-- should not generate diagnostics -->
<div role="button"></div>
<div role="switch" />
<div role></div>
<div></div>
<div baz />
<div role="button" />
<div role="switch row" />
<div />
<div role="tabpanel row" />
Loading