ltk/

nav_stack.rs

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

//! [`NavStack`]: the navigation state of a multi-screen app.

use serde::{ Deserialize, Serialize };

use crate::app::BackResponse;

/// The screens the user went through to get where they are, root first.
///
/// A plain value the app keeps in its model — the runtime never sees it.
/// It exists so the two things that must agree are one object: what
/// [`App::on_back`](crate::App::on_back) walks and what
/// [`App::save_state`](crate::App::save_state) persists. It serialises
/// whenever the route type does, and it is never empty: there is always a
/// root to fall back to, including after deserialising.
///
/// ```rust
/// use ltk::{ App, BackResponse, Element, NavStack, text };
/// use serde::{ Deserialize, Serialize };
///
/// #[ derive( Clone, PartialEq, Serialize, Deserialize ) ]
/// enum Route { Inbox, Thread( u64 ), Settings }
///
/// #[ derive( Clone ) ]
/// enum Msg { Open( Route ), Back }
///
/// struct Mail { nav: NavStack<Route> }
///
/// impl App for Mail
/// {
///     type Message = Msg;
///
///     fn app_id( &self ) -> &str { "net.example.Mail" }
///
///     fn view( &self ) -> Element<Msg>
///     {
///         let screen = match self.nav.current()
///         {
///             Route::Inbox        => text( "inbox" ),
///             Route::Thread( id ) => text( format!( "thread {id}" ) ),
///             Route::Settings     => text( "settings" ),
///         };
///         screen.into()
///     }
///
///     fn update( &mut self, msg: Msg )
///     {
///         match msg
///         {
///             Msg::Open( route ) => self.nav.push( route ),
///             Msg::Back          => { self.nav.pop(); }
///         }
///     }
///
///     fn on_back( &mut self ) -> BackResponse<Msg> { self.nav.back( Msg::Back ) }
///
///     fn save_state( &self ) -> Option<Vec<u8>> { serde_json::to_vec( &self.nav ).ok() }
///
///     fn restore_state( &mut self, state: Vec<u8> )
///     {
///         if let Ok( nav ) = serde_json::from_slice( &state ) { self.nav = nav; }
///     }
/// }
/// ```
#[ derive( Debug, Clone, PartialEq, Eq, Serialize, Deserialize ) ]
pub struct NavStack<R>
{
	root:  R,
	above: Vec<R>,
}

impl<R> NavStack<R>
{
	pub fn new( root: R ) -> Self
	{
		Self { root, above: Vec::new() }
	}

	/// The route on screen.
	pub fn current( &self ) -> &R
	{
		self.above.last().unwrap_or( &self.root )
	}

	pub fn current_mut( &mut self ) -> &mut R
	{
		self.above.last_mut().unwrap_or( &mut self.root )
	}

	/// Go to `route`, keeping the current one underneath.
	pub fn push( &mut self, route: R )
	{
		self.above.push( route );
	}

	/// Go back one route. `None` at the root, which stays.
	pub fn pop( &mut self ) -> Option<R>
	{
		self.above.pop()
	}

	/// Swap the current route for `route` without growing the stack — a
	/// sideways move (tab to tab, step to step) back should not retrace.
	/// Returns the route it replaced.
	pub fn replace( &mut self, route: R ) -> R
	{
		std::mem::replace( self.current_mut(), route )
	}

	pub fn pop_to_root( &mut self )
	{
		self.above.clear();
	}

	/// Start over from a new root.
	pub fn reset( &mut self, root: R )
	{
		self.root = root;
		self.above.clear();
	}

	pub fn can_pop( &self ) -> bool
	{
		!self.above.is_empty()
	}

	/// Number of routes, the root included.
	pub fn depth( &self ) -> usize
	{
		self.above.len() + 1
	}

	/// Routes from the root up to the current one.
	pub fn iter( &self ) -> impl Iterator<Item = &R>
	{
		std::iter::once( &self.root ).chain( self.above.iter() )
	}

	/// The answer for [`App::on_back`](crate::App::on_back): `pop` when
	/// there is a route to go back to, [`BackResponse::Unhandled`] at the
	/// root. `pop` is the app's message that ends up calling [`Self::pop`].
	pub fn back<M>( &self, pop: M ) -> BackResponse<M>
	{
		if self.can_pop() { BackResponse::Message( pop ) } else { BackResponse::Unhandled }
	}
}

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

	#[ test ]
	fn push_and_pop_walk_the_routes()
	{
		let mut nav = NavStack::new( "inbox" );
		nav.push( "thread" );
		nav.push( "attachment" );
		assert_eq!( *nav.current(), "attachment" );
		assert_eq!( nav.depth(), 3 );
		assert_eq!( nav.pop(), Some( "attachment" ) );
		assert_eq!( *nav.current(), "thread" );
	}

	#[ test ]
	fn the_root_cannot_be_popped()
	{
		let mut nav = NavStack::new( "inbox" );
		assert!( !nav.can_pop() );
		assert_eq!( nav.pop(), None );
		assert_eq!( *nav.current(), "inbox" );
	}

	#[ test ]
	fn replace_is_a_sideways_move()
	{
		let mut nav = NavStack::new( "inbox" );
		nav.push( "general" );
		assert_eq!( nav.replace( "network" ), "general" );
		assert_eq!( nav.depth(), 2 );
		nav.pop();
		assert_eq!( *nav.current(), "inbox" );

		let mut root_only = NavStack::new( "a" );
		root_only.replace( "b" );
		assert_eq!( *root_only.current(), "b" );
		assert!( !root_only.can_pop() );
	}

	#[ test ]
	fn back_is_unhandled_only_at_the_root()
	{
		let mut nav = NavStack::new( 0 );
		assert_eq!( nav.back( "pop" ), BackResponse::Unhandled );
		nav.push( 1 );
		assert_eq!( nav.back( "pop" ), BackResponse::Message( "pop" ) );
	}

	#[ test ]
	fn reset_and_pop_to_root()
	{
		let mut nav = NavStack::new( 0 );
		nav.push( 1 );
		nav.push( 2 );
		nav.pop_to_root();
		assert_eq!( nav.iter().copied().collect::<Vec<_>>(), vec![ 0 ] );
		nav.push( 1 );
		nav.reset( 9 );
		assert_eq!( nav.iter().copied().collect::<Vec<_>>(), vec![ 9 ] );
	}

	#[ test ]
	fn survives_a_serde_round_trip()
	{
		let mut nav = NavStack::new( "inbox".to_string() );
		nav.push( "thread".to_string() );
		let bytes    = serde_json::to_vec( &nav ).unwrap();
		let restored: NavStack<String> = serde_json::from_slice( &bytes ).unwrap();
		assert_eq!( restored, nav );
		assert!( restored.can_pop() );
	}
}