ltk/src/a11y/tree.rs

// SPDX-License-Identifier: LGPL-2.1-only
// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>

//! Construction of [`accesskit::TreeUpdate`] from the layout pass.

use std::collections::HashMap;

use accesskit::{ Action, Live, Node, NodeId, Rect as A11yRect, Role, TextPosition, TextSelection, Toggled, Tree, TreeUpdate };

use crate::types::Rect;
use crate::widget::{ LaidOutWidget, WidgetHandlers };

#[ derive( Clone ) ]
pub( crate ) enum AccessibleExtraKind
{
	Label,
	Image,
	Separator,
	Progress( f32 ),
}

#[ derive( Clone ) ]
pub( crate ) struct AccessibleExtra
{
	pub rect:  Rect,
	pub label: Option<String>,
	pub live:  bool,
	pub kind:  AccessibleExtraKind,
}

pub( crate ) const ROOT_ID: NodeId = NodeId( 1 );

const KIND_WIDGET:   u8 = 0;
const KIND_EXTRA:    u8 = 1;
const KIND_TEXT_RUN: u8 = 2;
const KIND_OVERLAY:  u8 = 3;
const ID_BASE: u64 = 1 << 48;

#[ inline ]
fn make_id( focus: u8, kind: u8, idx: u32 ) -> NodeId
{
	NodeId( ID_BASE | ( ( focus as u64 ) << 40 ) | ( ( kind as u64 ) << 32 ) | ( idx as u64 ) )
}

#[ derive( Clone, Copy, Debug, PartialEq, Eq ) ]
pub( crate ) struct NodeRef
{
	pub focus: u8,
	pub kind:  u8,
	pub idx:   u32,
}

#[ inline ]
pub( crate ) fn parse_id( id: NodeId ) -> Option<NodeRef>
{
	let v = id.0;
	if v < ID_BASE { return None; }
	Some( NodeRef
	{
		focus: ( ( v >> 40 ) & 0xFF ) as u8,
		kind:  ( ( v >> 32 ) & 0xFF ) as u8,
		idx:   ( v & 0xFFFF_FFFF ) as u32,
	} )
}

#[ inline ]
pub( crate ) fn widget_id_for( focus: u8, flat_idx: usize ) -> NodeId
{
	make_id( focus, KIND_WIDGET, flat_idx as u32 )
}

#[ inline ]
fn extra_id_for( focus: u8, idx: usize ) -> NodeId
{
	make_id( focus, KIND_EXTRA, idx as u32 )
}

#[ inline ]
fn text_run_id_for( focus: u8, flat_idx: usize ) -> NodeId
{
	make_id( focus, KIND_TEXT_RUN, flat_idx as u32 )
}

#[ inline ]
fn overlay_root_id( focus: u8 ) -> NodeId
{
	make_id( focus, KIND_OVERLAY, 0 )
}

pub( crate ) fn empty_root() -> TreeUpdate
{
	let mut root = Node::new( Role::Window );
	root.set_label( "ltk" );
	TreeUpdate
	{
		nodes: vec![ ( ROOT_ID, root ) ],
		tree:  Some( Tree::new( ROOT_ID ) ),
		focus: ROOT_ID,
	}
}

fn node_for<Msg: Clone>(
	focus_id:           u8,
	w:                  &LaidOutWidget<Msg>,
	is_focused:         bool,
	is_pressed:         bool,
	pending_text:       Option<&String>,
	cursor_byte:        usize,
	out_text_run:       &mut Option<( NodeId, Node )>,
) -> Node
{
	let role = match &w.handlers
	{
		WidgetHandlers::Button { .. }                => Role::Button,
		WidgetHandlers::Toggle { .. }                => Role::Switch,
		WidgetHandlers::Checkbox { .. }              => Role::CheckBox,
		WidgetHandlers::Radio { .. }                 => Role::RadioButton,
		WidgetHandlers::ListItem { .. }              => Role::ListItem,
		WidgetHandlers::WindowButton { .. }          => Role::Button,
		WidgetHandlers::Slider { .. }                => Role::Slider,
		WidgetHandlers::TextEdit { multiline, .. }   =>
			if *multiline { Role::MultilineTextInput } else { Role::TextInput },
		WidgetHandlers::None                          => Role::GenericContainer,
	};
	let mut node = Node::new( role );
	node.set_bounds( convert_rect( w.rect ) );
	if let Some( name ) = label_for( &w.handlers, w.accessible_label.as_deref(), w.tooltip.as_deref() )
	{
		node.set_label( name );
	}
	if w.handlers.is_disabled()
	{
		node.set_disabled();
	}
	match &w.handlers
	{
		WidgetHandlers::Button { .. } | WidgetHandlers::WindowButton { .. } | WidgetHandlers::ListItem { .. } =>
		{
			node.add_action( Action::Click );
			node.add_action( Action::Focus );
			if is_pressed { node.set_toggled( Toggled::True ); }
		}
		WidgetHandlers::Toggle { value, .. } =>
		{
			node.add_action( Action::Click );
			node.add_action( Action::Focus );
			node.set_toggled( if *value { Toggled::True } else { Toggled::False } );
		}
		WidgetHandlers::Checkbox { value, .. } =>
		{
			node.add_action( Action::Click );
			node.add_action( Action::Focus );
			node.set_toggled( if *value { Toggled::True } else { Toggled::False } );
		}
		WidgetHandlers::Radio { selected, .. } =>
		{
			node.add_action( Action::Click );
			node.add_action( Action::Focus );
			node.set_toggled( if *selected { Toggled::True } else { Toggled::False } );
		}
		WidgetHandlers::Slider { value, .. } =>
		{
			node.add_action( Action::Focus );
			node.add_action( Action::SetValue );
			node.add_action( Action::Increment );
			node.add_action( Action::Decrement );
			node.set_min_numeric_value( 0.0 );
			node.set_max_numeric_value( 1.0 );
			node.set_numeric_value_step( 0.05 );
			node.set_numeric_value( *value as f64 );
		}
		WidgetHandlers::TextEdit { value, secure, .. } =>
		{
			node.add_action( Action::Focus );
			node.add_action( Action::SetValue );
			let exposed: String = if *secure
			{
				String::new()
			}
			else
			{
				pending_text.cloned().unwrap_or_else( || value.clone() )
			};
			node.set_value( exposed.as_str() );

			let run_id = text_run_id_for( focus_id, w.flat_idx );
			node.set_children( vec![ run_id ] );

			let lengths: Vec<u8> = exposed.chars().map( |c| c.len_utf8() as u8 ).collect();
			let safe_byte        = cursor_byte.min( exposed.len() );
			let cursor_char_idx  = exposed[ ..safe_byte ].chars().count();
			let pos = TextPosition { node: run_id, character_index: cursor_char_idx };
			node.set_text_selection( TextSelection { anchor: pos, focus: pos } );

			let mut run = Node::new( Role::TextRun );
			run.set_bounds( convert_rect( w.rect ) );
			run.set_value( exposed.as_str() );
			run.set_character_lengths( lengths );
			*out_text_run = Some( ( run_id, run ) );
		}
		_ => {}
	}
	if is_focused
	{
		node.add_action( Action::Focus );
	}
	if w.is_live_region
	{
		node.set_live( Live::Polite );
	}
	node
}

#[ inline ]
fn convert_rect( r: Rect ) -> A11yRect
{
	A11yRect
	{
		x0: r.x as f64,
		y0: r.y as f64,
		x1: ( r.x + r.width  ) as f64,
		y1: ( r.y + r.height ) as f64,
	}
}

fn label_for<Msg: Clone>( handlers: &WidgetHandlers<Msg>, visible: Option<&str>, tooltip: Option<&str> ) -> Option<String>
{
	if let WidgetHandlers::TextEdit { secure: true, .. } = handlers
	{
		return Some( "password".to_string() );
	}
	visible.or( tooltip ).map( |s| s.to_string() )
}

pub( crate ) struct SurfaceView<'a, Msg: Clone>
{
	pub focus_id:            u8,
	pub is_main:             bool,
	pub label:               Option<&'a str>,
	pub widget_rects:        &'a [ LaidOutWidget<Msg> ],
	pub extras:              &'a [ AccessibleExtra ],
	pub focused_idx:         Option<usize>,
	pub pressed_idx:         Option<usize>,
	pub pending_text_values: &'a HashMap<usize, String>,
	pub cursor_state:        &'a HashMap<usize, usize>,
	pub width:               f32,
	pub height:              f32,
	pub offset_x:            f32,
	pub offset_y:            f32,
}

pub( crate ) fn build_tree<Msg: Clone>(
	surfaces:       &[ SurfaceView<Msg> ],
	keyboard_focus: u8,
	app_name:       &str,
) -> TreeUpdate
{
	let main = surfaces.iter().find( |s| s.is_main );
	let ( total_w, total_h ) = main.map( |m| ( m.width, m.height ) ).unwrap_or( ( 0.0, 0.0 ) );

	let mut nodes = Vec::new();

	let mut root = Node::new( Role::Window );
	root.set_label( app_name );
	root.set_bounds( A11yRect { x0: 0.0, y0: 0.0, x1: total_w as f64, y1: total_h as f64 } );
	let mut root_children: Vec<NodeId> = Vec::new();

	if let Some( m ) = main
	{
		for w in m.widget_rects { root_children.push( widget_id_for( m.focus_id, w.flat_idx ) ); }
		for ( i, _ ) in m.extras.iter().enumerate() { root_children.push( extra_id_for( m.focus_id, i ) ); }
	}
	for s in surfaces.iter().filter( |s| !s.is_main )
	{
		root_children.push( overlay_root_id( s.focus_id ) );
	}
	root.set_children( root_children );
	nodes.push( ( ROOT_ID, root ) );

	let mut active_focus: Option<NodeId> = None;

	for s in surfaces
	{
		if !s.is_main
		{
			let mut dlg = Node::new( Role::Dialog );
			if let Some( l ) = s.label { dlg.set_label( l ); }
			dlg.set_bounds( A11yRect
			{
				x0: s.offset_x as f64, y0: s.offset_y as f64,
				x1: ( s.offset_x + s.width ) as f64, y1: ( s.offset_y + s.height ) as f64,
			} );
			let mut ch: Vec<NodeId> = Vec::new();
			for w in s.widget_rects { ch.push( widget_id_for( s.focus_id, w.flat_idx ) ); }
			for ( i, _ ) in s.extras.iter().enumerate() { ch.push( extra_id_for( s.focus_id, i ) ); }
			dlg.set_children( ch );
			nodes.push( ( overlay_root_id( s.focus_id ), dlg ) );
		}

		for w in s.widget_rects
		{
			let is_focused  = s.focused_idx == Some( w.flat_idx );
			let is_pressed  = s.pressed_idx == Some( w.flat_idx );
			let pending     = s.pending_text_values.get( &w.flat_idx );
			let cursor_byte = s.cursor_state.get( &w.flat_idx ).copied().unwrap_or( usize::MAX );
			let mut text_run: Option<( NodeId, Node )> = None;
			let mut node = node_for( s.focus_id, w, is_focused, is_pressed, pending, cursor_byte, &mut text_run );
			if !s.is_main
			{
				let mut r = w.rect;
				r.x += s.offset_x;
				r.y += s.offset_y;
				node.set_bounds( convert_rect( r ) );
			}
			let id = widget_id_for( s.focus_id, w.flat_idx );
			if is_focused && s.focus_id == keyboard_focus
			{
				active_focus = Some( id );
			}
			nodes.push( ( id, node ) );
			if let Some( ( rid, run ) ) = text_run { nodes.push( ( rid, run ) ); }
		}

		for ( i, e ) in s.extras.iter().enumerate()
		{
			let role = match e.kind
			{
				AccessibleExtraKind::Label       => Role::Label,
				AccessibleExtraKind::Image       => Role::Image,
				AccessibleExtraKind::Separator   => Role::Splitter,
				AccessibleExtraKind::Progress(_) => Role::ProgressIndicator,
			};
			let mut node = Node::new( role );
			let mut r = e.rect;
			if !s.is_main { r.x += s.offset_x; r.y += s.offset_y; }
			node.set_bounds( convert_rect( r ) );
			if let Some( ref l ) = e.label { node.set_label( l.as_str() ); }
			if let AccessibleExtraKind::Progress( v ) = e.kind
			{
				node.set_min_numeric_value( 0.0 );
				node.set_max_numeric_value( 1.0 );
				node.set_numeric_value( v as f64 );
			}
			if e.live { node.set_live( Live::Polite ); }
			nodes.push( ( extra_id_for( s.focus_id, i ), node ) );
		}
	}

	let focus = active_focus.unwrap_or( ROOT_ID );

	TreeUpdate
	{
		nodes,
		tree: Some( Tree::new( ROOT_ID ) ),
		focus,
	}
}

#[ cfg( test ) ]
mod tests
{
	use super::*;

	#[ test ]
	fn id_round_trip()
	{
		for focus in [ 0u8, 1, 7, 200 ]
		{
			for idx in [ 0usize, 1, 42, 9999 ]
			{
				let id = widget_id_for( focus, idx );
				let r  = parse_id( id ).expect( "parses" );
				assert_eq!( ( r.focus, r.kind, r.idx as usize ), ( focus, KIND_WIDGET, idx ) );
			}
		}
	}

	#[ test ]
	fn root_is_not_a_widget()
	{
		assert!( parse_id( ROOT_ID ).is_none() );
		assert!( parse_id( NodeId( 0 ) ).is_none() );
	}
}