Various accessibility API updates. (bevyengine#9989)

# Objective

`bevy_a11y` was impossible to integrate into some third-party projects
in part because it insisted on managing the accessibility tree on its
own.

## Solution

The changes in this PR were necessary to get `bevy_egui` working with
Bevy's AccessKit integration. They were tested on a fork of 0.11,
developed against `bevy_egui`, then ported to main and tested against
the `ui` example.

## Changelog

### Changed

* Add `bevy_a11y::ManageAccessibilityUpdates` to indicate whether the
ECS should manage accessibility tree updates.
* Add getter/setter to `bevy_a11y::AccessibilityRequested`.
* Add `bevy_a11y::AccessibilitySystem` `SystemSet` for ordering relative
to accessibility tree updates.
* Upgrade `accesskit` to v0.12.0.

### Fixed

* Correctly set initial accessibility focus to new windows on creation.

## Migration Guide

### Change direct accesses of `AccessibilityRequested` to use
`AccessibilityRequested.::get()`/`AccessibilityRequested::set()`

#### Before

```
use std::sync::atomic::Ordering;

// To access
accessibility_requested.load(Ordering::SeqCst)
// To update
accessibility_requested.store(true, Ordering::SeqCst);
```

#### After

```
// To access
accessibility_requested.get()
// To update
accessibility_requested.set(true);
```

---------

Co-authored-by: StaffEngineer <[email protected]>

crates/bevy_a11y/Cargo.toml

@@ -14,4 +14,4 @@ bevy_app = { path = "../bevy_app", version = "0.12.0-dev" }
 bevy_derive = { path = "../bevy_derive", version = "0.12.0-dev" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.12.0-dev" }
 
-accesskit = "0.11"
+accesskit = "0.12"

crates/bevy_a11y/src/lib.rs

@@ -4,17 +4,18 @@
 #![allow(clippy::type_complexity)]
 #![forbid(unsafe_code)]
 
-use std::{
-    num::NonZeroU128,
-    sync::{atomic::AtomicBool, Arc},
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    Arc,
 };
 
 pub use accesskit;
-use accesskit::{NodeBuilder, NodeId};
+use accesskit::NodeBuilder;
 use bevy_app::Plugin;
 use bevy_derive::{Deref, DerefMut};
 use bevy_ecs::{
     prelude::{Component, Entity, Event},
+    schedule::SystemSet,
     system::Resource,
 };
 
@@ -30,6 +31,46 @@ pub struct ActionRequest(pub accesskit::ActionRequest);
 #[derive(Resource, Default, Clone, Debug, Deref, DerefMut)]
 pub struct AccessibilityRequested(Arc<AtomicBool>);
 
+impl AccessibilityRequested {
+    /// Returns `true` if an access technology is active and accessibility tree
+    /// updates should be sent.
+    pub fn get(&self) -> bool {
+        self.load(Ordering::SeqCst)
+    }
+
+    /// Sets whether accessibility updates were requested by an access technology.
+    pub fn set(&self, value: bool) {
+        self.store(value, Ordering::SeqCst);
+    }
+}
+
+/// Resource whose value determines whether the accessibility tree is updated
+/// via the ECS.
+///
+/// Set to `false` in cases where an external GUI library is sending
+/// accessibility updates instead. Without this, the external library and ECS
+/// will generate conflicting updates.
+#[derive(Resource, Clone, Debug, Deref, DerefMut)]
+pub struct ManageAccessibilityUpdates(bool);
+
+impl Default for ManageAccessibilityUpdates {
+    fn default() -> Self {
+        Self(true)
+    }
+}
+
+impl ManageAccessibilityUpdates {
+    /// Returns `true` if the ECS should update the accessibility tree.
+    pub fn get(&self) -> bool {
+        self.0
+    }
+
+    /// Sets whether the ECS should update the accessibility tree.
+    pub fn set(&mut self, value: bool) {
+        self.0 = value;
+    }
+}
+
 /// Component to wrap a [`accesskit::Node`], representing this entity to the platform's
 /// accessibility API.
 ///
@@ -47,29 +88,24 @@ impl From<NodeBuilder> for AccessibilityNode {
     }
 }
 
-/// Extensions to ease integrating entities with [`AccessKit`](https://accesskit.dev).
-pub trait AccessKitEntityExt {
-    /// Convert an entity to a stable [`NodeId`].
-    fn to_node_id(&self) -> NodeId;
-}
-
-impl AccessKitEntityExt for Entity {
-    fn to_node_id(&self) -> NodeId {
-        let id = NonZeroU128::new(self.to_bits() as u128 + 1);
-        NodeId(id.unwrap())
-    }
-}
-
 /// Resource representing which entity has keyboard focus, if any.
 #[derive(Resource, Default, Deref, DerefMut)]
-pub struct Focus(Option<Entity>);
+pub struct Focus(pub Option<Entity>);
+
+/// Set enum for the systems relating to accessibility
+#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
+pub enum AccessibilitySystem {
+    /// Update the accessibility tree
+    Update,
+}
 
 /// Plugin managing non-GUI aspects of integrating with accessibility APIs.
 pub struct AccessibilityPlugin;
 
 impl Plugin for AccessibilityPlugin {
     fn build(&self, app: &mut bevy_app::App) {
         app.init_resource::<AccessibilityRequested>()
+            .init_resource::<ManageAccessibilityUpdates>()
             .init_resource::<Focus>();
     }
 }

crates/bevy_ui/src/accessibility.rs

@@ -124,14 +124,14 @@ fn label_changed(
             .collect::<Vec<String>>();
         let name = Some(values.join(" ").into_boxed_str());
         if let Some(mut accessible) = accessible {
-            accessible.set_role(Role::LabelText);
+            accessible.set_role(Role::StaticText);
             if let Some(name) = name {
                 accessible.set_name(name);
             } else {
                 accessible.clear_name();
             }
         } else {
-            let mut node = NodeBuilder::new(Role::LabelText);
+            let mut node = NodeBuilder::new(Role::StaticText);
             if let Some(name) = name {
                 node.set_name(name);
             }

crates/bevy_window/Cargo.toml

@@ -14,6 +14,7 @@ serialize = ["serde"]
 
 [dependencies]
 # bevy
+bevy_a11y = { path = "../bevy_a11y", version = "0.12.0-dev" }
 bevy_app = { path = "../bevy_app", version = "0.12.0-dev" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.12.0-dev" }
 bevy_math = { path = "../bevy_math", version = "0.12.0-dev" }

crates/bevy_window/src/lib.rs

@@ -7,6 +7,8 @@
 //! The [`WindowPlugin`] sets up some global window-related parameters and
 //! is part of the [`DefaultPlugins`](https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html).
 
+use bevy_a11y::Focus;
+
 mod cursor;
 mod event;
 mod raw_handle;
@@ -99,9 +101,14 @@ impl Plugin for WindowPlugin {
             .add_event::<WindowThemeChanged>();
 
         if let Some(primary_window) = &self.primary_window {
-            app.world
+            let initial_focus = app
+                .world
                 .spawn(primary_window.clone())
-                .insert(PrimaryWindow);
+                .insert(PrimaryWindow)
+                .id();
+            if let Some(mut focus) = app.world.get_resource_mut::<Focus>() {
+                **focus = Some(initial_focus);
+            }
         }
 
         match self.exit_condition {

crates/bevy_winit/Cargo.toml

@@ -29,7 +29,7 @@ bevy_tasks = { path = "../bevy_tasks", version = "0.12.0-dev" }
 
 # other
 winit = { version = "0.28.7", default-features = false }
-accesskit_winit = { version = "0.14", default-features = false }
+accesskit_winit = { version = "0.15", default-features = false }
 approx = { version = "0.5", default-features = false }
 raw-window-handle = "0.5"
 

crates/bevy_winit/src/accessibility.rs

@@ -2,25 +2,28 @@
 
 use std::{
     collections::VecDeque,
-    sync::{atomic::Ordering, Arc, Mutex},
+    sync::{Arc, Mutex},
 };
 
 use accesskit_winit::Adapter;
-use bevy_a11y::ActionRequest as ActionRequestWrapper;
 use bevy_a11y::{
-    accesskit::{ActionHandler, ActionRequest, NodeBuilder, NodeClassSet, Role, TreeUpdate},
-    AccessKitEntityExt, AccessibilityNode, AccessibilityRequested, Focus,
+    accesskit::{
+        ActionHandler, ActionRequest, NodeBuilder, NodeClassSet, NodeId, Role, TreeUpdate,
+    },
+    AccessibilityNode, AccessibilityRequested, AccessibilitySystem, Focus,
 };
+use bevy_a11y::{ActionRequest as ActionRequestWrapper, ManageAccessibilityUpdates};
 use bevy_app::{App, Plugin, PostUpdate};
 use bevy_derive::{Deref, DerefMut};
 use bevy_ecs::{
     prelude::{DetectChanges, Entity, EventReader, EventWriter},
     query::With,
+    schedule::IntoSystemConfigs,
     system::{NonSend, NonSendMut, Query, Res, ResMut, Resource},
 };
 use bevy_hierarchy::{Children, Parent};
-use bevy_utils::{default, HashMap};
-use bevy_window::{PrimaryWindow, Window, WindowClosed, WindowFocused};
+use bevy_utils::HashMap;
+use bevy_window::{PrimaryWindow, Window, WindowClosed};
 
 /// Maps window entities to their `AccessKit` [`Adapter`]s.
 #[derive(Default, Deref, DerefMut)]
@@ -35,34 +38,12 @@ pub struct WinitActionHandlers(pub HashMap<Entity, WinitActionHandler>);
 pub struct WinitActionHandler(pub Arc<Mutex<VecDeque<ActionRequest>>>);
 
 impl ActionHandler for WinitActionHandler {
-    fn do_action(&self, request: ActionRequest) {
+    fn do_action(&mut self, request: ActionRequest) {
         let mut requests = self.0.lock().unwrap();
         requests.push_back(request);
     }
 }
 
-fn handle_window_focus(
-    focus: Res<Focus>,
-    adapters: NonSend<AccessKitAdapters>,
-    mut focused: EventReader<WindowFocused>,
-) {
-    for event in focused.read() {
-        if let Some(adapter) = adapters.get(&event.window) {
-            adapter.update_if_active(|| {
-                let focus_id = (*focus).unwrap_or_else(|| event.window);
-                TreeUpdate {
-                    focus: if event.focused {
-                        Some(focus_id.to_node_id())
-                    } else {
-                        None
-                    },
-                    ..default()
-                }
-            });
-        }
-    }
-}
-
 fn window_closed(
     mut adapters: NonSendMut<AccessKitAdapters>,
     mut receivers: ResMut<WinitActionHandlers>,
@@ -86,10 +67,16 @@ fn poll_receivers(
     }
 }
 
+fn should_update_accessibility_nodes(
+    accessibility_requested: Res<AccessibilityRequested>,
+    manage_accessibility_updates: Res<ManageAccessibilityUpdates>,
+) -> bool {
+    accessibility_requested.get() && manage_accessibility_updates.get()
+}
+
 fn update_accessibility_nodes(
     adapters: NonSend<AccessKitAdapters>,
     focus: Res<Focus>,
-    accessibility_requested: Res<AccessibilityRequested>,
     primary_window: Query<(Entity, &Window), With<PrimaryWindow>>,
     nodes: Query<(
         Entity,
@@ -99,46 +86,37 @@ fn update_accessibility_nodes(
     )>,
     node_entities: Query<Entity, With<AccessibilityNode>>,
 ) {
-    if !accessibility_requested.load(Ordering::SeqCst) {
-        return;
-    }
     if let Ok((primary_window_id, primary_window)) = primary_window.get_single() {
         if let Some(adapter) = adapters.get(&primary_window_id) {
             let should_run = focus.is_changed() || !nodes.is_empty();
             if should_run {
                 adapter.update_if_active(|| {
                     let mut to_update = vec![];
-                    let mut has_focus = false;
                     let mut name = None;
                     if primary_window.focused {
-                        has_focus = true;
                         let title = primary_window.title.clone();
                         name = Some(title.into_boxed_str());
                     }
-                    let focus_id = if has_focus {
-                        (*focus).or_else(|| Some(primary_window_id))
-                    } else {
-                        None
-                    };
+                    let focus_id = (*focus).unwrap_or_else(|| primary_window_id).to_bits();
                     let mut root_children = vec![];
                     for (entity, node, children, parent) in &nodes {
                         let mut node = (**node).clone();
                         if let Some(parent) = parent {
-                            if node_entities.get(**parent).is_err() {
-                                root_children.push(entity.to_node_id());
+                            if !node_entities.contains(**parent) {
+                                root_children.push(NodeId(entity.to_bits()));
                             }
                         } else {
-                            root_children.push(entity.to_node_id());
+                            root_children.push(NodeId(entity.to_bits()));
                         }
                         if let Some(children) = children {
                             for child in children {
-                                if node_entities.get(*child).is_ok() {
-                                    node.push_child(child.to_node_id());
+                                if node_entities.contains(*child) {
+                                    node.push_child(NodeId(child.to_bits()));
                                 }
                             }
                         }
                         to_update.push((
-                            entity.to_node_id(),
+                            NodeId(entity.to_bits()),
                             node.build(&mut NodeClassSet::lock_global()),
                         ));
                     }
@@ -148,12 +126,12 @@ fn update_accessibility_nodes(
                     }
                     root.set_children(root_children);
                     let root = root.build(&mut NodeClassSet::lock_global());
-                    let window_update = (primary_window_id.to_node_id(), root);
+                    let window_update = (NodeId(primary_window_id.to_bits()), root);
                     to_update.insert(0, window_update);
                     TreeUpdate {
                         nodes: to_update,
-                        focus: focus_id.map(|v| v.to_node_id()),
-                        ..default()
+                        tree: None,
+                        focus: NodeId(focus_id),
                     }
                 });
             }
@@ -171,12 +149,13 @@ impl Plugin for AccessibilityPlugin {
             .add_event::<ActionRequestWrapper>()
             .add_systems(
                 PostUpdate,
-                (
-                    handle_window_focus,
-                    window_closed,
-                    poll_receivers,
-                    update_accessibility_nodes,
-                ),
+                (window_closed, poll_receivers).in_set(AccessibilitySystem::Update),
+            )
+            .add_systems(
+                PostUpdate,
+                update_accessibility_nodes
+                    .run_if(should_update_accessibility_nodes)
+                    .in_set(AccessibilitySystem::Update),
             );
     }
 }

crates/bevy_winit/src/winit_windows.rs

@@ -1,10 +1,9 @@
 #![warn(missing_docs)]
-use std::sync::atomic::Ordering;
 
 use accesskit_winit::Adapter;
 use bevy_a11y::{
-    accesskit::{NodeBuilder, NodeClassSet, Role, Tree, TreeUpdate},
-    AccessKitEntityExt, AccessibilityRequested,
+    accesskit::{NodeBuilder, NodeClassSet, NodeId, Role, Tree, TreeUpdate},
+    AccessibilityRequested,
 };
 use bevy_ecs::entity::Entity;
 
@@ -151,17 +150,17 @@ impl WinitWindows {
         root_builder.set_name(name.into_boxed_str());
         let root = root_builder.build(&mut NodeClassSet::lock_global());
 
-        let accesskit_window_id = entity.to_node_id();
+        let accesskit_window_id = NodeId(entity.to_bits());
         let handler = WinitActionHandler::default();
-        let accessibility_requested = (*accessibility_requested).clone();
+        let accessibility_requested = accessibility_requested.clone();
         let adapter = Adapter::with_action_handler(
             &winit_window,
             move || {
-                accessibility_requested.store(true, Ordering::SeqCst);
+                accessibility_requested.set(true);
                 TreeUpdate {
                     nodes: vec![(accesskit_window_id, root)],
                     tree: Some(Tree::new(accesskit_window_id)),
-                    focus: None,
+                    focus: accesskit_window_id,
                 }
             },
             Box::new(handler.clone()),