ftui_a11y/
lib.rs

1#![forbid(unsafe_code)]
2
3//! Accessibility layer for FrankenTUI.
4//!
5//! # Role in FrankenTUI
6//!
7//! `ftui-a11y` defines the accessibility tree infrastructure that lets
8//! widgets describe themselves to screen readers and other assistive
9//! technology. It is **Phase 1** of the accessibility initiative: the
10//! core types and trait contract.
11//!
12//! # Architecture
13//!
14//! ```text
15//!  Widget ──impl Accessible──> Vec<A11yNodeInfo>
16//!                                     │
17//!                              A11yTreeBuilder::add_node()
18//!                                     │
19//!                              A11yTreeBuilder::build()
20//!                                     │
21//!                                A11yTree (immutable snapshot)
22//!                                     │
23//!                              A11yTree::diff(&prev)
24//!                                     │
25//!                               A11yTreeDiff
26//!                                     │
27//!              screen-reader mirror + live announcements
28//!                                     │
29//!                          (future: platform bridge)
30//! ```
31//!
32//! # How it fits in the system
33//!
34//! - **`ftui-core`**: provides `Rect` for node bounding boxes.
35//! - **`ftui-widgets`**: widgets will `impl Accessible` in a future phase.
36//! - **`ftui-render`**: the render pass will collect nodes via the builder.
37//! - **Platform bridges** (future Phase 3): consume `A11yTreeDiff`,
38//!   screen-reader mirror text, and bounded live announcements to push
39//!   updates to AccessKit / platform APIs.
40//!
41//! # Quick start
42//!
43//! ```rust
44//! use ftui_a11y::node::{A11yNodeInfo, A11yRole};
45//! use ftui_a11y::tree::A11yTreeBuilder;
46//! use ftui_core::geometry::Rect;
47//!
48//! // Build a small tree.
49//! let mut builder = A11yTreeBuilder::new();
50//! let root = A11yNodeInfo::new(1, A11yRole::Window, Rect::new(0, 0, 80, 24))
51//!     .with_name("My App")
52//!     .with_children(vec![2]);
53//! let button = A11yNodeInfo::new(2, A11yRole::Button, Rect::new(10, 5, 8, 1))
54//!     .with_name("OK")
55//!     .with_parent(1);
56//! builder.add_node(root);
57//! builder.add_node(button);
58//! builder.set_root(1);
59//! builder.set_focused(Some(2));
60//! let tree = builder.build();
61//!
62//! assert_eq!(tree.node_count(), 2);
63//! assert_eq!(tree.focused().unwrap().name.as_deref(), Some("OK"));
64//! ```
65
66pub mod node;
67pub mod tree;
68
69use ftui_core::geometry::Rect;
70use node::A11yNodeInfo;
71
72// ── Accessible trait ───────────────────────────────────────────────────
73
74/// Trait for widgets that provide accessibility metadata.
75///
76/// Implementing this trait is **opt-in**. Widgets that do not implement
77/// it are invisible to screen readers (treated as presentational /
78/// decorative).
79///
80/// # Contract
81///
82/// - `accessibility_nodes` must return at least one node for the widget.
83/// - The first node in the returned `Vec` is the widget's "primary"
84///   node; additional nodes represent internal structure (e.g. a table
85///   widget returns the table node plus row/cell nodes).
86/// - Node IDs must be unique within a single render pass. Use a
87///   deterministic scheme (e.g. widget identity hash) to keep IDs
88///   stable across frames for efficient diffing.
89/// - `area` is the bounding rectangle the widget was laid out into.
90///
91/// # Example
92///
93/// ```rust
94/// use ftui_core::geometry::Rect;
95/// use ftui_a11y::Accessible;
96/// use ftui_a11y::node::{A11yNodeInfo, A11yRole};
97///
98/// struct MyButton {
99///     label: String,
100///     id: u64,
101/// }
102///
103/// impl Accessible for MyButton {
104///     fn accessibility_nodes(&self, area: Rect) -> Vec<A11yNodeInfo> {
105///         vec![
106///             A11yNodeInfo::new(self.id, A11yRole::Button, area)
107///                 .with_name(&self.label)
108///         ]
109///     }
110/// }
111/// ```
112pub trait Accessible {
113    /// Return accessibility node(s) for this widget at the given bounds.
114    ///
115    /// Container widgets should return a parent node with children IDs,
116    /// plus the child nodes themselves.
117    fn accessibility_nodes(&self, area: Rect) -> Vec<A11yNodeInfo>;
118}
ftui_a11y/lib.rs

ftui_a11y/
lib.rs
