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.

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.

Warning: Popping a non-top modal with a focus group will NOT restore focus correctly. The focus trap stack is LIFO, so only the top modal’s trap can be safely popped. Prefer using pop() for correct focus handling.

Behavior

• If the modal is the top modal and has a focus group, pop_trap() is called
• If the modal is NOT the top modal, the focus trap is NOT popped (would corrupt state)

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) -> 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.

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

Render all modals.

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 stack_mut(&mut self) -> &mut ModalStack

Get a mutable reference to the underlying modal stack.

Warning: Direct manipulation may desync focus state.

pub fn focus_manager(&self) -> &FocusManager

Get a reference to the focus manager.

pub fn focus_manager_mut(&mut self) -> &mut FocusManager

Get a mutable reference to the focus manager.

Trait Implementations

impl Default for FocusAwareModalStack

fn default() -> Self

Returns the “default value” for a type.