Skip to main content

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}