Struct FocusAwareModalStack 

pub struct FocusAwareModalStack { /* private fields */ }

Modal stack with integrated focus management.

This wrapper provides automatic focus trapping when modals open and focus restoration when they close. It manages both the modal stack and focus manager in a coordinated way.

Invariants

• Focus trap stack depth equals the number of modals with focus groups.
• Each modal’s focus group ID is unique and not reused.
• Pop operations always call pop_trap for modals with focus groups.

Implementations

impl FocusAwareModalStack

pub fn new() -> Self

Create a new focus-aware modal stack.

pub fn with_focus_manager(focus_manager: FocusManager) -> Self

Create from existing stack and focus manager.

Use this when you already have a FocusManager in your application and want to integrate modal focus trapping.

The provided manager must not already have active modal traps. This wrapper only tracks traps for modals it owns, so starting from an already-trapped manager would make later rebuild/pop operations silently corrupt unrelated trap state.

pub fn push(&mut self, modal: Box<dyn StackModal>) -> ModalId

Push a modal without focus trapping.

The modal will be rendered and receive events, but focus is not managed.

pub fn push_with_trap( &mut self, modal: Box<dyn StackModal>, focusable_ids: Vec<FocusId>, ) -> ModalId

Push a modal with automatic focus trapping.

Parameters

• modal: The modal content
• focusable_ids: The focus IDs of elements inside the modal

Behavior

1. Creates a focus group with the provided IDs
2. Pushes a focus trap (saving current focus)
3. Moves focus to the first element in the group

pub fn pop(&mut self) -> Option<ModalResult>

Pop the top modal.

If the modal had a focus group, the focus trap is popped and focus is restored to where it was before the modal opened.

pub fn pop_id(&mut self, id: ModalId) -> Option<ModalResult>

Pop a specific modal by ID.

pub fn pop_all(&mut self) -> Vec<ModalResult>

Pop all modals, restoring focus to the original state.

pub fn handle_event( &mut self, event: &Event, hit: Option<HitTestResult>, ) -> Option<ModalResult>

Handle an event, routing to the top modal.

If the modal closes (via Escape, backdrop click, etc.), the focus trap is automatically popped and focus is restored. For mouse events, pass the provenance-aware result from Frame::hit_test_detailed.

pub fn render(&self, frame: &mut Frame<'_>, screen: Rect)

Render all modals.

pub fn with_focus_graph_mut<R>( &mut self, f: impl FnOnce(&mut FocusGraph) -> R, ) -> R

Perform a direct focus-graph mutation and automatically resynchronize modal focus state.

pub fn focus(&mut self, id: FocusId) -> Option<FocusId>

Focus a specific target through the wrapped focus manager.

pub fn is_empty(&self) -> bool

Check if the modal stack is empty.

pub fn depth(&self) -> usize

Get the number of open modals.

pub fn is_focus_trapped(&self) -> bool

Check if focus is currently trapped in a modal.

pub fn stack(&self) -> &ModalStack

Get a reference to the underlying modal stack.

pub fn focus_manager(&self) -> &FocusManager

Get a reference to the focus manager.

Trait Implementations

impl Default for FocusAwareModalStack

fn default() -> Self

Returns the “default value” for a type.