teksilo_widgets/table_view/

a11y.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! Accessibility wrappers for `TableView` / `TreeTableView`.
//!
//! AccessKit's table semantics work by labelling individual nodes with
//! `Role::Table` / `Role::Row` / `Role::Cell` and stamping each cell with
//! its row/column index. The cell delegate the user supplies typically
//! produces a generic widget (Text, Button, …) that wouldn't carry table
//! semantics by itself, so the body wraps each cell in a thin
//! `CellA11y` node. `TableView`'s row containers themselves
//! (`BodyRow`) carry `Role::Row` and
//! row-index metadata directly. `TreeTableView` wraps each row in a
//! `TreeRowA11y` instead, to declare `set_level` and `set_expanded`, and
//! mirrors the level onto the tree column's cell as well — `CellA11y::
//! with_level` says why the row alone is not heard.
//!
//! These wrappers do not paint or affect layout: they pass the proposed
//! size straight through to their single child and forward all bounds.

use teksilo_canvas::{Rect, SizeProposal};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::widget::{LayoutContext, Widget, WidgetPlacement};
use teksilo_core::widget_id::WidgetId;

use teksilo_data::SortDirection;

/// Wrapper that announces a `Role::Cell` (or `Role::RowHeader`) with
/// row/column indices and selection state.
#[derive(Debug)]
pub(crate) struct CellA11y {
    child: WidgetId,
    row_index_1based: usize,
    col_index_1based: usize,
    selected: bool,
    /// When true, emit `Role::RowHeader` instead of `Role::Cell` — used
    /// when the table promotes a column to row-header status.
    is_row_header: bool,
    /// Whether the cell is itself the selectable unit.
    ///
    /// Decides `Role::GridCell` over `Role::Cell`, which is not cosmetic on
    /// Windows: `accesskit_windows` supports UIA's `SelectionItem` pattern for
    /// `GridCell` unconditionally and for `Role::Cell` not at all, so a
    /// selected cell announced as `Cell` never reports `IsSelected`. The two
    /// map identically on macOS (`NSAccessibilityCellRole`) and AT-SPI
    /// (`TableCell`), so this costs nothing there.
    is_grid_cell: bool,
    /// Optional name override (when the cell content isn't textual).
    name: Option<String>,
    /// 1-based hierarchy level, mirrored from the row this cell belongs to.
    ///
    /// `None` on a flat table, and on every column of a tree table but the
    /// one that draws the indent. See `with_level`.
    level_1based: Option<usize>,
    /// Expand state of the row this cell belongs to: `Some(true|false)` on a
    /// branch, `None` on a leaf and on every cell that is not the tree
    /// column's. See `with_expanded`.
    expanded: Option<bool>,
    /// How many columns the cell covers, when it covers more than its own.
    /// See `with_column_span`.
    column_span: Option<usize>,
}

impl CellA11y {
    pub(crate) fn new(
        child: WidgetId,
        row_index_1based: usize,
        col_index_1based: usize,
        selected: bool,
    ) -> Self {
        Self {
            child,
            row_index_1based,
            col_index_1based,
            selected,
            is_row_header: false,
            is_grid_cell: false,
            name: None,
            level_1based: None,
            expanded: None,
            column_span: None,
        }
    }

    /// Announce `Role::GridCell` — the cell is the selectable unit. Named for
    /// the sibling `with_role_row_header`, not `as_*`, which clippy reserves
    /// for by-reference conversions.
    pub(crate) fn with_grid_cell_role(mut self, is_grid_cell: bool) -> Self {
        self.is_grid_cell = is_grid_cell;
        self
    }

    /// Promote to `Role::RowHeader` (`row_header_column` support).
    #[allow(dead_code)]
    pub(crate) fn with_role_row_header(mut self, is_row_header: bool) -> Self {
        self.is_row_header = is_row_header;
        self
    }

    /// Override the cell's accessible name (`cell_label_fn`).
    #[allow(dead_code)]
    pub(crate) fn with_name(mut self, name: Option<String>) -> Self {
        self.name = name;
        self
    }

    /// Mirror the row's 1-based hierarchy level onto this cell.
    ///
    /// The depth belongs to the *row*, and `TreeRowA11y` publishes it there.
    /// But `TreeTableView` navigates by cell: it nominates the focused *cell*
    /// as the container's `active_descendant`, which leaves the row an
    /// ancestor of the focused node — and NVDA drops `positionInfo_level`
    /// from an ancestor it announces on the way in (`speech.py` clears
    /// `allowProperties["positionInfo_level"]` for
    /// `OutputReason.FOCUSENTERED`). So the depth was published correctly on
    /// the row and spoken nowhere. `TreeView` does not have this problem: its
    /// rows *are* the focused nodes.
    ///
    /// Only the tree column asks for this. It is the column that draws the
    /// indent and the chevron, so it is the one whose announcement matches
    /// what is on screen, and repeating "level 3" on all seven columns of one
    /// row is noise. The price is that arrowing *down* a non-tree column
    /// announces no depth change; the tree column is one arrow away, and
    /// mirroring everywhere to close that gap would charge every horizontal
    /// move for it.
    ///
    /// Windows-only in effect, and not because of this decision: `level` is
    /// the one positional property `accesskit_macos-0.27.0` and
    /// `accesskit_atspi_common-0.20.0` do not expose at all (the latter
    /// publishes `posinset` / `setsize` and no `level`). VoiceOver and Orca
    /// heard nothing from the row either — for them the indent is what
    /// carries depth.
    pub(crate) fn with_level(mut self, level_1based: Option<usize>) -> Self {
        self.level_1based = level_1based;
        self
    }

    /// Mirror the row's expand state onto this cell — same reason as
    /// `with_level`, and one more.
    ///
    /// Announcing it is the first reason: "expanded" is a *state*, and a
    /// screen reader reads the states of the node it is on, which here is the
    /// cell. But a state on an ancestor fails a second way that a level does
    /// not. Toggling a row with ArrowRight moves nothing, so no focus event
    /// follows; all the user has to go on is a property change, and
    /// `accesskit_windows` raises that on the node whose property changed —
    /// the row, which is not the focused element, so NVDA drops it. Opening
    /// and closing a branch was silent.
    ///
    /// The state owes an answer, and already has one. `accesskit_consumer`
    /// derives UIA's ExpandCollapse pattern from the *property*, not from the
    /// action list, so a cell that declares a state will be sent `Expand` and
    /// `Collapse` whether or not anything handles them — the
    /// advertised-and-inert bug the row's own call site fixed. Nothing new is
    /// needed for the cell: an `AccessAction` bubbles, and the row carrying
    /// that pair is on the cell's path to the root. Handlers on the cell as
    /// well would only run `set_expanded_at` twice.
    pub(crate) fn with_expanded(mut self, expanded: Option<bool>) -> Self {
        self.expanded = expanded;
        self
    }

    /// Announce that the cell covers `span` columns (`aria-colspan`), from its
    /// own column index on. `TreeTableView`'s full-width rows are one cell
    /// across every column and say so here.
    ///
    /// Published, not yet heard: none of the adapters this workspace pins
    /// (`accesskit_windows` 0.35, `accesskit_macos` 0.27,
    /// `accesskit_atspi_common` 0.21) reads `column_span`. It is the property
    /// AccessKit defines for exactly this, on the node it belongs to, so an
    /// adapter that learns it needs nothing more from here.
    pub(crate) fn with_column_span(mut self, span: Option<usize>) -> Self {
        self.column_span = span;
        self
    }
}

impl Widget for CellA11y {
    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        ctx.child_size(self.child, proposal)
            .unwrap_or_else(|| proposal.resolve(0.0, 0.0))
            .into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        _ctx: &LayoutContext,
    ) {
        for child in children.iter_mut() {
            child.origin = bounds.origin();
            child.size = bounds.size();
        }
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        builder.set_role(if self.is_row_header {
            teksilo_core::accesskit::Role::RowHeader
        } else if self.is_grid_cell {
            teksilo_core::accesskit::Role::GridCell
        } else {
            teksilo_core::accesskit::Role::Cell
        });
        if let Some(ref name) = self.name {
            builder.set_name(name.clone());
        }
        builder.set_selected(self.selected);
        builder.set_row_index(self.row_index_1based);
        builder.set_column_index(self.col_index_1based);
        // The floor matches `TreeRowA11y`: a caller that computed a depth of
        // 0 lands on the root level, not one above it.
        if let Some(level) = self.level_1based {
            builder.set_level(level.max(1));
        }
        // A leaf declares nothing, which UIA reads as `LeafNode` — the state
        // a cell with no subtree should report, and the reason this is not a
        // plain `bool`.
        if let Some(expanded) = self.expanded {
            builder.set_expanded(expanded);
        }
        if let Some(span) = self.column_span {
            builder.set_column_span(span);
        }
    }

    fn children(&self) -> Vec<WidgetId> {
        vec![self.child]
    }
}

/// `TreeTableView`-flavoured row wrapper. Announces `Role::Row` and, in
/// addition to the row index, declares `set_level` (1-based depth),
/// `set_expanded` when the row has children, and `set_position_in_set`
/// among the row's siblings, mirroring what `TreeView`'s `TreeItemWrapper`
/// (`list_item_a11y.rs`) announces, so both widgets say which sibling a
/// row is.
///
/// No `size_of_set` goes with it, here or on the container: AccessKit
/// resolves a set size by walking up from the item, and a flattened tree has
/// no per-branch node to hold one, so neither widget can say "of 5". The
/// comment in `accessibility` below spells out what expressing it would cost.
#[derive(Debug)]
pub(crate) struct TreeRowA11y {
    child: WidgetId,
    row_index_1based: usize,
    /// 1-based hierarchy level (root rows are 1).
    level_1based: usize,
    /// `Some(true|false)` for non-leaf rows; `None` for leaves.
    expanded: Option<bool>,
    selected: bool,
    /// 1-based position among this row's siblings (`TreeSource::sibling_pos`).
    position_in_set: usize,
}

impl TreeRowA11y {
    pub(crate) fn new(
        child: WidgetId,
        row_index_1based: usize,
        level_1based: usize,
        expanded: Option<bool>,
        selected: bool,
        position_in_set: usize,
    ) -> Self {
        Self {
            child,
            row_index_1based,
            level_1based,
            expanded,
            selected,
            position_in_set,
        }
    }
}

impl Widget for TreeRowA11y {
    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        ctx.child_size(self.child, proposal)
            .unwrap_or_else(|| proposal.resolve(0.0, 0.0))
            .into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        _ctx: &LayoutContext,
    ) {
        for child in children.iter_mut() {
            child.origin = bounds.origin();
            child.size = bounds.size();
        }
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        builder.set_role(teksilo_core::accesskit::Role::Row);
        builder.set_selected(self.selected);
        if let Some(exp) = self.expanded {
            builder.set_expanded(exp);
        }
        builder.set_row_index(self.row_index_1based);
        // The floor keeps a caller that computed a depth of 0 on the root
        // level rather than one above it. `set_level` takes the ARIA 1-based
        // number and converts to AccessKit's zero-based property itself.
        builder.set_level(self.level_1based.max(1));
        builder.set_position_in_set(self.position_in_set);
        // No `size_of_set` here, and none on the container either.
        //
        // AccessKit resolves an item's set size by walking *up* from it
        // (`size_of_set_from_container`), so the only value a flattened tree
        // could publish is one shared by every row at every depth — which is
        // not what "the 2nd of 5 siblings" means. Expressing it correctly needs
        // a real `Role::Group` node per expanded branch, between the container
        // and its rows, and that changes the AT tree shape for every tree
        // widget. Writing the number on this node instead is dead: no adapter
        // on any platform reads it, and leaving it there makes a missing
        // feature look like a working one.
        //
        // The level and the expanded state still carry the hierarchy, and
        // `position_in_set` still says which sibling this is.
    }

    fn children(&self) -> Vec<WidgetId> {
        vec![self.child]
    }
}

/// Header column wrapper — `Role::ColumnHeader` with sort direction
/// when this is the active sort column.
#[derive(Debug)]
#[allow(dead_code)]
pub(crate) struct ColumnHeaderA11y {
    child: WidgetId,
    col_index_1based: usize,
    name: String,
    sort: Option<SortDirection>,
}

#[allow(dead_code)] // not wired: `HeaderCell` publishes its own node
impl ColumnHeaderA11y {
    pub(crate) fn new(
        child: WidgetId,
        col_index_1based: usize,
        name: impl Into<String>,
        sort: Option<SortDirection>,
    ) -> Self {
        Self {
            child,
            col_index_1based,
            name: name.into(),
            sort,
        }
    }
}

impl Widget for ColumnHeaderA11y {
    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        ctx.child_size(self.child, proposal)
            .unwrap_or_else(|| proposal.resolve(0.0, 0.0))
            .into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        _ctx: &LayoutContext,
    ) {
        for child in children.iter_mut() {
            child.origin = bounds.origin();
            child.size = bounds.size();
        }
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        builder.set_role(teksilo_core::accesskit::Role::ColumnHeader);
        builder.set_name(self.name.clone());
        builder.set_column_index(self.col_index_1based);
        if let Some(dir) = self.sort {
            let ak_dir = match dir {
                SortDirection::Ascending => teksilo_core::accesskit::SortDirection::Ascending,
                SortDirection::Descending => teksilo_core::accesskit::SortDirection::Descending,
            };
            builder.inner_mut().set_sort_direction(ak_dir);
        }
    }

    fn children(&self) -> Vec<WidgetId> {
        vec![self.child]
    }
}