Skip to main content

sui_platform/
accessibility.rs

1use std::collections::{HashMap, HashSet};
2
3use sui_core::{SemanticsAction, SemanticsNode, SemanticsRole, WidgetId, WindowId};
4
5#[derive(Debug, Clone, PartialEq)]
6pub struct AccessibilitySnapshot {
7    pub window_id: WindowId,
8    pub root: Option<WidgetId>,
9    pub focused_widget: Option<WidgetId>,
10    pub nodes: Vec<SemanticsNode>,
11}
12
13impl AccessibilitySnapshot {
14    pub fn new(window_id: WindowId, nodes: Vec<SemanticsNode>) -> Self {
15        let root = nodes
16            .iter()
17            .find(|node| node.parent.is_none())
18            .map(|node| node.id);
19        let focused_widget = nodes
20            .iter()
21            .find(|node| node.state.focused)
22            .map(|node| node.id);
23
24        Self {
25            window_id,
26            root,
27            focused_widget,
28            nodes,
29        }
30    }
31}
32
33#[derive(Debug, Clone, Default)]
34pub(crate) struct AccessibilityBridge {
35    snapshot: Option<AccessibilitySnapshot>,
36}
37
38impl AccessibilityBridge {
39    pub(crate) fn snapshot(&self) -> Option<&AccessibilitySnapshot> {
40        self.snapshot.as_ref()
41    }
42
43    pub(crate) fn update(&mut self, window_id: WindowId, nodes: Vec<SemanticsNode>) {
44        self.snapshot = Some(AccessibilitySnapshot::new(window_id, nodes));
45    }
46}
47
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
49pub enum AccessibilityIssueSeverity {
50    Error,
51    Warning,
52    Info,
53}
54
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56pub enum AccessibilityIssueTarget {
57    Snapshot,
58    Node(WidgetId),
59}
60
61#[derive(Debug, Clone, PartialEq, Eq)]
62pub struct AccessibilityIssue {
63    pub severity: AccessibilityIssueSeverity,
64    pub target: AccessibilityIssueTarget,
65    pub message: String,
66}
67
68impl AccessibilityIssue {
69    fn new(
70        severity: AccessibilityIssueSeverity,
71        target: AccessibilityIssueTarget,
72        message: impl Into<String>,
73    ) -> Self {
74        Self {
75            severity,
76            target,
77            message: message.into(),
78        }
79    }
80}
81
82/// Validate a semantic snapshot using the shared accessibility contract used
83/// by inspectors, terminal rendering, and test tooling.
84pub fn validate_accessibility_snapshot(
85    snapshot: &AccessibilitySnapshot,
86) -> Vec<AccessibilityIssue> {
87    let mut issues = Vec::new();
88    let roots = snapshot
89        .nodes
90        .iter()
91        .filter(|node| node.parent.is_none())
92        .collect::<Vec<_>>();
93    if roots.is_empty() {
94        issues.push(AccessibilityIssue::new(
95            AccessibilityIssueSeverity::Error,
96            AccessibilityIssueTarget::Snapshot,
97            "accessibility snapshot has no root node",
98        ));
99    } else if roots.len() > 1 {
100        issues.push(AccessibilityIssue::new(
101            AccessibilityIssueSeverity::Error,
102            AccessibilityIssueTarget::Snapshot,
103            format!("accessibility snapshot has {} root nodes", roots.len()),
104        ));
105    }
106    if let Some(root) = snapshot.root
107        && !snapshot.nodes.iter().any(|node| node.id == root)
108    {
109        issues.push(AccessibilityIssue::new(
110            AccessibilityIssueSeverity::Error,
111            AccessibilityIssueTarget::Snapshot,
112            format!("snapshot root #{root} is missing from nodes"),
113        ));
114    }
115
116    let mut counts = HashMap::<WidgetId, usize>::new();
117    for node in &snapshot.nodes {
118        *counts.entry(node.id).or_default() += 1;
119    }
120    for (&id, &count) in counts.iter().filter(|(_, count)| **count > 1) {
121        issues.push(AccessibilityIssue::new(
122            AccessibilityIssueSeverity::Error,
123            AccessibilityIssueTarget::Node(id),
124            format!("duplicate accessibility node id #{id} appears {count} times"),
125        ));
126    }
127    let ids = counts.keys().copied().collect::<HashSet<_>>();
128    let parents = snapshot
129        .nodes
130        .iter()
131        .map(|node| (node.id, node.parent))
132        .collect::<HashMap<_, _>>();
133    for node in &snapshot.nodes {
134        if let Some(parent) = node.parent {
135            if !ids.contains(&parent) {
136                issues.push(AccessibilityIssue::new(
137                    AccessibilityIssueSeverity::Error,
138                    AccessibilityIssueTarget::Node(node.id),
139                    format!("node #{} references missing parent #{parent}", node.id),
140                ));
141            }
142            if parent == node.id {
143                issues.push(AccessibilityIssue::new(
144                    AccessibilityIssueSeverity::Error,
145                    AccessibilityIssueTarget::Node(node.id),
146                    format!("node #{} cannot parent itself", node.id),
147                ));
148            }
149        }
150        let mut seen = HashSet::new();
151        let mut current = Some(node.id);
152        while let Some(id) = current {
153            if !seen.insert(id) {
154                issues.push(AccessibilityIssue::new(
155                    AccessibilityIssueSeverity::Error,
156                    AccessibilityIssueTarget::Node(node.id),
157                    format!("node #{} has a cyclic parent chain", node.id),
158                ));
159                break;
160            }
161            current = parents.get(&id).copied().flatten();
162        }
163    }
164
165    if let Some(focused) = snapshot.focused_widget {
166        match snapshot.nodes.iter().find(|node| node.id == focused) {
167            Some(node) if node.state.hidden => issues.push(AccessibilityIssue::new(
168                AccessibilityIssueSeverity::Warning,
169                AccessibilityIssueTarget::Node(focused),
170                format!("focused node #{focused} is hidden"),
171            )),
172            Some(_) => {}
173            None => issues.push(AccessibilityIssue::new(
174                AccessibilityIssueSeverity::Error,
175                AccessibilityIssueTarget::Snapshot,
176                format!("focused widget #{focused} is missing from nodes"),
177            )),
178        }
179    }
180
181    for node in &snapshot.nodes {
182        if interactive_role(node)
183            && !node.state.hidden
184            && node.name.as_deref().unwrap_or_default().trim().is_empty()
185        {
186            issues.push(AccessibilityIssue::new(
187                AccessibilityIssueSeverity::Error,
188                AccessibilityIssueTarget::Node(node.id),
189                format!(
190                    "{:?} node #{} is missing accessible name",
191                    node.role, node.id
192                ),
193            ));
194        }
195        for action in expected_actions(node) {
196            if !node.actions.contains(&action) {
197                issues.push(AccessibilityIssue::new(
198                    AccessibilityIssueSeverity::Warning,
199                    AccessibilityIssueTarget::Node(node.id),
200                    format!(
201                        "{:?} node #{} is missing expected action {:?}",
202                        node.role, node.id, action
203                    ),
204                ));
205            }
206        }
207        if value_role(node) && node.value.is_none() {
208            issues.push(AccessibilityIssue::new(
209                AccessibilityIssueSeverity::Warning,
210                AccessibilityIssueTarget::Node(node.id),
211                format!("{:?} node #{} is missing value", node.role, node.id),
212            ));
213        }
214        if !node.state.hidden && interactive_role(node) && node.bounds.is_empty() {
215            issues.push(AccessibilityIssue::new(
216                AccessibilityIssueSeverity::Warning,
217                AccessibilityIssueTarget::Node(node.id),
218                format!("visible actionable node #{} has empty bounds", node.id),
219            ));
220        }
221        if node.parent.is_some_and(|parent| {
222            snapshot
223                .nodes
224                .iter()
225                .find(|candidate| candidate.id == parent)
226                .is_some_and(|parent| parent.state.hidden)
227        }) && !node.state.hidden
228        {
229            issues.push(AccessibilityIssue::new(
230                AccessibilityIssueSeverity::Warning,
231                AccessibilityIssueTarget::Node(node.id),
232                format!("visible node #{} has a hidden parent", node.id),
233            ));
234        }
235    }
236
237    let mut visible_names = HashMap::<(String, String), Vec<WidgetId>>::new();
238    for node in snapshot.nodes.iter().filter(|node| {
239        !node.state.hidden
240            && interactive_role(node)
241            && node
242                .name
243                .as_deref()
244                .is_some_and(|name| !name.trim().is_empty())
245    }) {
246        visible_names
247            .entry((
248                format!("{:?}", node.role),
249                node.name.clone().unwrap_or_default(),
250            ))
251            .or_default()
252            .push(node.id);
253    }
254    for ((role, name), ids) in visible_names.into_iter().filter(|(_, ids)| ids.len() > 1) {
255        issues.push(AccessibilityIssue::new(
256            AccessibilityIssueSeverity::Warning,
257            AccessibilityIssueTarget::Snapshot,
258            format!(
259                "duplicate visible actionable role/name {role} {name:?} on nodes {:?}",
260                ids.iter().map(|id| id.get()).collect::<Vec<_>>()
261            ),
262        ));
263    }
264
265    issues
266}
267
268fn interactive_role(node: &SemanticsNode) -> bool {
269    matches!(
270        node.role,
271        SemanticsRole::Button
272            | SemanticsRole::CheckBox
273            | SemanticsRole::Switch
274            | SemanticsRole::RadioButton
275            | SemanticsRole::MenuItem
276            | SemanticsRole::Slider
277            | SemanticsRole::TextInput
278            | SemanticsRole::SpinBox
279            | SemanticsRole::ComboBox
280            | SemanticsRole::ColorPicker
281            | SemanticsRole::ScrollView
282    )
283}
284
285fn value_role(node: &SemanticsNode) -> bool {
286    matches!(
287        node.role,
288        SemanticsRole::Slider
289            | SemanticsRole::ProgressBar
290            | SemanticsRole::TextInput
291            | SemanticsRole::SpinBox
292            | SemanticsRole::ComboBox
293            | SemanticsRole::ColorPicker
294    )
295}
296
297fn expected_actions(node: &SemanticsNode) -> Vec<SemanticsAction> {
298    match node.role {
299        SemanticsRole::Button
300        | SemanticsRole::CheckBox
301        | SemanticsRole::Switch
302        | SemanticsRole::RadioButton
303        | SemanticsRole::MenuItem => vec![SemanticsAction::Activate],
304        SemanticsRole::TextInput | SemanticsRole::ComboBox | SemanticsRole::ColorPicker => {
305            vec![SemanticsAction::Focus, SemanticsAction::SetValue]
306        }
307        SemanticsRole::Slider | SemanticsRole::SpinBox => vec![
308            SemanticsAction::Focus,
309            SemanticsAction::Increment,
310            SemanticsAction::Decrement,
311        ],
312        SemanticsRole::ScrollView => vec![SemanticsAction::Focus],
313        _ => Vec::new(),
314    }
315}