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