kernel/accessibility.rs
1// Copyright 2026 Mark Alan Boykin
2// This Source Code Form is subject to the terms of the Mozilla Public
3// License, v. 2.0. If a copy of the MPL was not distributed with this
4// file, You can obtain one at https://mozilla.org/MPL/2.0/.
5// SPDX-License-Identifier: MPL-2.0
6
7//! Host-neutral accessibility descriptors keyed by [`SurfaceId`].
8//!
9//! Provides a portable contract every Graphshell host can honor for
10//! AccessKit instrumentation. The vendored iced fork doesn't yet
11//! expose AccessKit hooks through its widget tree; this module's job
12//! is to lock the shape in regardless — the descriptor lookup is
13//! addressable today (tests assert completeness), and a future host
14//! integration (or a future iced version that gains AccessKit
15//! support) renders descriptors into AccessKit nodes via this single
16//! lookup.
17//!
18//! ## Design choices
19//!
20//! - **AccessKit roles directly.** No bespoke role enum — we adopt
21//! `accesskit::Role` so future hosts that wire AccessKit don't have
22//! to translate. AccessKit is the de-facto cross-platform a11y
23//! layer (used by egui, winit, GTK, AT-SPI, UI Automation, NSAccessibility).
24//! - **Keyed by `SurfaceId`, not stored on widgets.** Widgets stay
25//! `From<T>`-conversion-shaped (no need to add `.label(...)`
26//! builders to every gs widget). The descriptor lookup is the
27//! single source of truth — change the role once, every host
28//! picks it up.
29//! - **Static const-ish data**. `descriptor_for` is a pure function
30//! over `SurfaceId`. Hosts can call it from anywhere without
31//! threading a registry.
32//!
33//! ## Slice 24 status
34//!
35//! This module ships the lookup + tests. Iced does *not* render the
36//! descriptors today (iced's vendored fork has no AccessKit hooks).
37//! When that gap closes, the integration is one place: the iced
38//! widget conversions emit AccessKit nodes built from
39//! `descriptor_for(surface_id)`. Future hosts (egui, Stage-G/H) do
40//! the same against their respective AccessKit bridges.
41
42use accesskit::Role;
43use serde::{Deserialize, Serialize};
44
45/// Identifier for a chrome surface that emits UX events. Adding a new
46/// surface (e.g., a future "Inspector" pane) is one new variant here
47/// and one new emission site at the surface's open/dismiss seams.
48#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
49pub enum SurfaceId {
50 Omnibar,
51 CommandPalette,
52 NodeFinder,
53 ContextMenu,
54 ConfirmDialog,
55 /// Modal that prompts the user for a URL when an action like
56 /// `NodeNew` fires from a non-omnibar surface (palette, context
57 /// menu, programmatic).
58 NodeCreate,
59 /// Modal that prompts the user for a new label when the
60 /// `FrameRename` action fires.
61 FrameRename,
62 StatusBar,
63 TreeSpine,
64 NavigatorHost,
65 /// A tile pane (tile-tabs + body). The variant is the granular
66 /// surface; per-pane discrimination (PaneId) is host-side state
67 /// and not carried in the `UxEvent` payload today — extending
68 /// `UxEvent::SurfaceOpened` with a target field is queued as a
69 /// future enrichment when downstream observers need it.
70 TilePane,
71 /// A canvas pane. Same per-pane discrimination caveat as
72 /// [`Self::TilePane`].
73 CanvasPane,
74 /// The canvas base layer (empty Frame fallback).
75 BaseLayer,
76 /// The graph roster pane: node manifest/list for the current graph.
77 RosterPane,
78 /// The inspector pane: selected object provenance, trust, parse diagnostics,
79 /// document structure, local cache state, and lineage.
80 InspectorPane,
81 /// The steward pane: live async operations and actionable actor/job state.
82 StewardPane,
83 /// The gloss pane: outline, swatch, and subgraph navigation surface.
84 GlossPane,
85 /// The apparatus pane: system diagnostics, settings, probes, and a11y status.
86 ApparatusPane,
87 /// The comms pane: mail/cabal conversations.
88 CommsPane,
89 /// The tiled workbench pane.
90 WorkbenchPane,
91}
92
93/// A surface's accessibility metadata. Carries the AccessKit role
94/// plus the visible label, an optional longer description (used as
95/// the AccessKit `description` field — read by screen readers when
96/// the user dwells on the surface), and an optional keyboard-shortcut
97/// hint surfaced both visually and as the AccessKit `keyboard_shortcuts`
98/// field so AT users can discover the binding.
99///
100/// Any one host may consume more or fewer of these fields depending
101/// on its AccessKit integration depth. The portable contract is:
102/// every surface declares all four; hosts use what they can.
103#[derive(Debug, Clone, PartialEq, Eq)]
104pub struct AccessibilityDescriptor {
105 /// Maps to `accesskit::Node::set_role`. Serialized as the
106 /// numeric discriminant via accesskit's `serde` feature.
107 pub role: Role,
108 /// Visible label (`accesskit::Node::set_label`). Required —
109 /// every surface ships with a non-empty label.
110 pub label: &'static str,
111 /// Longer description for screen readers
112 /// (`accesskit::Node::set_description`). Optional.
113 pub description: Option<&'static str>,
114 /// Keyboard shortcut hint (e.g. "Ctrl+Shift+P") —
115 /// `accesskit::Node::set_keyboard_shortcuts`. Optional.
116 pub keyboard_shortcut: Option<&'static str>,
117}
118
119impl AccessibilityDescriptor {
120 /// Apply this descriptor to an `accesskit::Node` builder. Used
121 /// by host integrations once their AccessKit bridge is wired.
122 /// Today no host calls this; tests verify the shape compiles.
123 pub fn apply(&self, node: &mut accesskit::Node) {
124 node.set_role(self.role);
125 node.set_label(self.label);
126 if let Some(desc) = self.description {
127 node.set_description(desc);
128 }
129 if let Some(ks) = self.keyboard_shortcut {
130 node.set_keyboard_shortcut(ks);
131 }
132 }
133}
134
135/// The canonical descriptor for a surface. Pure function over
136/// [`SurfaceId`]; the result is the single source of truth every
137/// host renders identically.
138pub fn descriptor_for(surface: SurfaceId) -> AccessibilityDescriptor {
139 match surface {
140 SurfaceId::Omnibar => AccessibilityDescriptor {
141 role: Role::TextInput,
142 label: "Address bar",
143 description: Some(
144 "URL entry and breadcrumb display. Type a URL and \
145 press Enter to open it as a node.",
146 ),
147 keyboard_shortcut: Some("Ctrl+L"),
148 },
149 SurfaceId::CommandPalette => AccessibilityDescriptor {
150 role: Role::Dialog,
151 label: "Command palette",
152 description: Some(
153 "Search and run any registered Graphshell action. \
154 Type to filter; arrow keys to navigate; Enter to run.",
155 ),
156 keyboard_shortcut: Some("Ctrl+Shift+P"),
157 },
158 SurfaceId::NodeFinder => AccessibilityDescriptor {
159 role: Role::Dialog,
160 label: "Node finder",
161 description: Some(
162 "Search graph nodes by title, tag, URL, or content. \
163 Type to filter; arrow keys to navigate; Enter to open.",
164 ),
165 keyboard_shortcut: Some("Ctrl+P"),
166 },
167 SurfaceId::ContextMenu => AccessibilityDescriptor {
168 role: Role::Menu,
169 label: "Context menu",
170 description: Some("Actions available for the right-clicked target."),
171 keyboard_shortcut: None,
172 },
173 SurfaceId::ConfirmDialog => AccessibilityDescriptor {
174 role: Role::AlertDialog,
175 label: "Confirm destructive action",
176 description: Some(
177 "Press Confirm to proceed with the destructive action, \
178 or Cancel / Escape to abandon it.",
179 ),
180 keyboard_shortcut: None,
181 },
182 SurfaceId::NodeCreate => AccessibilityDescriptor {
183 role: Role::Dialog,
184 label: "Create node",
185 description: Some(
186 "Enter a URL or address. Press Enter to create the \
187 node, or Cancel / Escape to abandon.",
188 ),
189 keyboard_shortcut: None,
190 },
191 SurfaceId::FrameRename => AccessibilityDescriptor {
192 role: Role::Dialog,
193 label: "Rename frame",
194 description: Some(
195 "Enter a new label for the active Frame. Press Enter \
196 to apply, or Cancel / Escape to abandon.",
197 ),
198 keyboard_shortcut: None,
199 },
200 SurfaceId::StatusBar => AccessibilityDescriptor {
201 role: Role::ContentInfo,
202 label: "Status bar",
203 description: Some(
204 "Ambient runtime indicators: ready state, dispatched \
205 actions, pending intent queue depth, focused node.",
206 ),
207 keyboard_shortcut: None,
208 },
209 SurfaceId::TreeSpine => AccessibilityDescriptor {
210 role: Role::Tree,
211 label: "Tree spine",
212 description: Some("Structural list of nodes in the current workbench."),
213 keyboard_shortcut: None,
214 },
215 SurfaceId::NavigatorHost => AccessibilityDescriptor {
216 role: Role::Navigation,
217 label: "Navigator host",
218 description: Some(
219 "Sidebar or toolbar host containing the Tree Spine, \
220 Swatches, and Activity Log buckets.",
221 ),
222 keyboard_shortcut: None,
223 },
224 SurfaceId::TilePane => AccessibilityDescriptor {
225 role: Role::TabPanel,
226 label: "Tile pane",
227 description: Some(
228 "Pane showing the active tiles of a subgraph. \
229 Right-click for tile actions.",
230 ),
231 keyboard_shortcut: None,
232 },
233 SurfaceId::CanvasPane => AccessibilityDescriptor {
234 role: Role::Canvas,
235 label: "Graph canvas pane",
236 description: Some(
237 "Force-directed canvas of graph nodes. Left-drag to \
238 pan, scroll to zoom, right-click on a node for \
239 actions.",
240 ),
241 keyboard_shortcut: None,
242 },
243 SurfaceId::BaseLayer => AccessibilityDescriptor {
244 role: Role::Canvas,
245 label: "Graph canvas",
246 description: Some(
247 "Default home view of the current graph. Right-click \
248 for graph-level actions.",
249 ),
250 keyboard_shortcut: None,
251 },
252 SurfaceId::RosterPane => AccessibilityDescriptor {
253 role: Role::List,
254 label: "Roster pane",
255 description: Some("List of graph nodes with their current content state."),
256 keyboard_shortcut: Some("Ctrl+R"),
257 },
258 SurfaceId::InspectorPane => AccessibilityDescriptor {
259 role: Role::Complementary,
260 label: "Inspector pane",
261 description: Some(
262 "Selected object details: provenance, trust, parse diagnostics, document structure, cache state, and lineage.",
263 ),
264 keyboard_shortcut: None,
265 },
266 SurfaceId::StewardPane => AccessibilityDescriptor {
267 role: Role::Complementary,
268 label: "Steward pane",
269 description: Some(
270 "Live async operations and actionable actor state: fetches, sync, retries, background work, and jobs.",
271 ),
272 keyboard_shortcut: None,
273 },
274 SurfaceId::GlossPane => AccessibilityDescriptor {
275 role: Role::Navigation,
276 label: "Gloss pane",
277 description: Some("Navigator surface for outlines, swatches, and subgraphs."),
278 keyboard_shortcut: Some("Ctrl+G"),
279 },
280 SurfaceId::ApparatusPane => AccessibilityDescriptor {
281 role: Role::Complementary,
282 label: "Apparatus pane",
283 description: Some("System diagnostics, probes, accessibility status, and settings."),
284 keyboard_shortcut: Some("Ctrl+,"),
285 },
286 SurfaceId::CommsPane => AccessibilityDescriptor {
287 role: Role::Complementary,
288 label: "Comms pane",
289 description: Some("Mail and cabal conversation surface."),
290 keyboard_shortcut: None,
291 },
292 SurfaceId::WorkbenchPane => AccessibilityDescriptor {
293 role: Role::TabPanel,
294 label: "Workbench pane",
295 description: Some("Tiled live node workbench."),
296 keyboard_shortcut: Some("Ctrl+T"),
297 },
298 }
299}
300
301// ---------------------------------------------------------------------------
302// Tests
303// ---------------------------------------------------------------------------
304
305#[cfg(test)]
306mod tests {
307 use super::*;
308
309 /// Every variant of `SurfaceId` must have a non-empty label.
310 /// Adding a new surface variant without a descriptor breaks this
311 /// test — that's the point. The lookup stays exhaustive.
312 #[test]
313 fn every_surface_has_a_non_empty_label() {
314 for surface in [
315 SurfaceId::Omnibar,
316 SurfaceId::CommandPalette,
317 SurfaceId::NodeFinder,
318 SurfaceId::ContextMenu,
319 SurfaceId::ConfirmDialog,
320 SurfaceId::NodeCreate,
321 SurfaceId::FrameRename,
322 SurfaceId::StatusBar,
323 SurfaceId::TreeSpine,
324 SurfaceId::NavigatorHost,
325 SurfaceId::TilePane,
326 SurfaceId::CanvasPane,
327 SurfaceId::BaseLayer,
328 SurfaceId::RosterPane,
329 SurfaceId::InspectorPane,
330 SurfaceId::StewardPane,
331 SurfaceId::GlossPane,
332 SurfaceId::ApparatusPane,
333 SurfaceId::CommsPane,
334 SurfaceId::WorkbenchPane,
335 ] {
336 let d = descriptor_for(surface);
337 assert!(
338 !d.label.is_empty(),
339 "{surface:?} ships with an empty a11y label",
340 );
341 }
342 }
343
344 /// Descriptors with shortcut hints must include the modifier
345 /// (Ctrl / Cmd / Alt / Shift) so the AT can announce it
346 /// canonically rather than reading "P" alone.
347 #[test]
348 fn keyboard_shortcuts_include_modifier_keys() {
349 for surface in [
350 SurfaceId::Omnibar,
351 SurfaceId::CommandPalette,
352 SurfaceId::NodeFinder,
353 ] {
354 let d = descriptor_for(surface);
355 let ks = d
356 .keyboard_shortcut
357 .expect("this surface should ship with a shortcut hint");
358 assert!(
359 ks.contains("Ctrl") || ks.contains("Cmd") || ks.contains("Alt"),
360 "{surface:?} shortcut hint missing modifier: {ks}",
361 );
362 }
363 }
364
365 #[test]
366 fn apply_writes_role_and_label_to_accesskit_node() {
367 let d = descriptor_for(SurfaceId::ConfirmDialog);
368 let mut node = accesskit::Node::new(d.role);
369 d.apply(&mut node);
370 // `accesskit::Node` doesn't expose role/label getters
371 // directly here; we rely on the apply() being a no-panic
372 // invocation as a smoke test. The real verification is at
373 // host-integration time when an AccessKit tree is built.
374 let _ = node;
375 }
376}