Skip to main content

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}