ltk/widget/tab_strip/

mod.rs

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

//! TabStrip — the open documents of an app, as a browser or a terminal shows them.

mod cards;
mod desktop;
mod icons;
mod mobile;
mod motion;
mod overview;
mod parts;
pub( crate ) mod row;
mod theme;
#[ cfg( test ) ]
mod tests;

use std::sync::Arc;

use crate::types::Color;
use crate::wallpaper::ImageData;
use super::Element;

pub use motion::TabMotion;
pub use overview::{ tab_overview, TabOverview };
pub use cards::TabCards;
pub use row::{ TabCells, TabRow };

/// The form a [`TabStrip`] takes.
#[ derive( Debug, Clone, Copy, PartialEq, Eq, Default ) ]
pub enum TabLayout
{
	/// A strip of every tab.
	#[ default ]
	Desktop,
	/// A bar with the active tab and a counter.
	Mobile,
}

/// The colours of a [`TabStrip`] and its [`TabOverview`]. The default follows the theme.
#[ derive( Debug, Clone, Copy, PartialEq ) ]
pub struct TabStripColors
{
	/// Behind the strip, the phone bar and the overview.
	pub strip:       Color,
	/// Text and icons drawn on the strip itself: the phone bar's title, the counter, the overview's header.
	pub ink:         Color,
	pub active_fill: Color,
	pub active_edge: Color,
	pub active_ink:  Color,
	pub idle_fill:   Color,
	pub idle_edge:   Color,
	pub idle_ink:    Color,
}

impl Default for TabStripColors
{
	fn default() -> Self
	{
		let palette = crate::theme::palette();
		Self
		{
			strip:       palette.surface_alt,
			ink:         palette.text_primary,
			active_fill: palette.accent,
			active_edge: palette.accent,
			active_ink:  palette.text_primary,
			idle_fill:   palette.surface,
			idle_edge:   palette.text_secondary,
			idle_ink:    palette.text_secondary,
		}
	}
}

impl TabStripColors
{
	pub( crate ) fn of( &self, active: bool ) -> ( Color, Color, Color )
	{
		if active { ( self.active_fill, self.active_edge, self.active_ink ) } else { ( self.idle_fill, self.idle_edge, self.idle_ink ) }
	}
}

#[ derive( Clone ) ]
pub( crate ) enum TabIcon
{
	Image( ImageData ),
	/// A symbolic theme icon, drawn in the colour of the tab's text.
	Symbol( String ),
}

/// One tab: a key that stays the same while it is open, which its animation follows, and what it shows.
#[ derive( Clone ) ]
pub struct TabItem
{
	pub( crate ) key:      u64,
	pub( crate ) label:    String,
	pub( crate ) icon:     Option<TabIcon>,
	pub( crate ) closable: bool,
}

impl TabItem
{
	pub fn new( key: u64, label: impl Into<String> ) -> Self
	{
		Self { key, label: label.into(), icon: None, closable: true }
	}

	/// An icon of its own, such as a page's favicon.
	pub fn image( mut self, image: ImageData ) -> Self
	{
		self.icon = Some( TabIcon::Image( image ) );
		self
	}

	/// A symbolic icon of the theme, by its catalogue name.
	pub fn symbol( mut self, name: impl Into<String> ) -> Self
	{
		self.icon = Some( TabIcon::Symbol( name.into() ) );
		self
	}

	/// Whether it has a close button. Default: `true`.
	pub fn closable( mut self, closable: bool ) -> Self
	{
		self.closable = closable;
		self
	}
}

/// Create a [`TabItem`].
pub fn tab( key: u64, label: impl Into<String> ) -> TabItem
{
	TabItem::new( key, label )
}

type IndexMsg<Msg> = Arc<dyn Fn( usize ) -> Msg>;

/// The open documents, as a strip on a desktop and a bar on a phone.
///
/// On a desktop, a strip of tabs with their icon, title and close button, sharing the width between a minimum and a part of the
/// screen and scrolling sideways when even the minimum does not fit; buttons may go before the tabs, right after the last one
/// and at the far right, and part of the width is always left clear. On a phone, a bar with the active tab and a counter that
/// asks for the [`TabOverview`], a grid of cards of every tab.
///
/// The widget is stateless but for its [`TabMotion`], which the app keeps so tabs grow, shrink and slide as they open and close:
///
/// ```rust,no_run
/// # use ltk::{ tab, tab_strip, Element, TabLayout, TabMotion };
/// # #[ derive( Clone ) ] enum Msg { Select( usize ), Close( usize ), Overview }
/// # struct App { titles: Vec<( u64, String )>, active: usize, motion: TabMotion, phone: bool }
/// # impl App { fn _ex( &self ) -> Element<Msg> {
/// tab_strip( self.titles.iter().map( |( key, title )| tab( *key, title.clone() ).symbol( "features/console" ) ) )
///     .selected( self.active )
///     .on_select( Msg::Select )
///     .on_close( Msg::Close )
///     .on_overview( Msg::Overview )
///     .layout( if self.phone { TabLayout::Mobile } else { TabLayout::Desktop } )
///     .motion( &self.motion )
///     .into()
/// # }}
/// ```
pub struct TabStrip<Msg: Clone>
{
	pub( crate ) tabs:        Vec<TabItem>,
	pub( crate ) selected:    usize,
	pub( crate ) on_select:   Option<IndexMsg<Msg>>,
	pub( crate ) on_close:    Option<IndexMsg<Msg>>,
	pub( crate ) on_overview: Option<Msg>,
	pub( crate ) reorderable: bool,
	pub( crate ) leading:     Vec<Element<Msg>>,
	pub( crate ) after:       Vec<Element<Msg>>,
	pub( crate ) trailing:    Vec<Element<Msg>>,
	pub( crate ) center:      Option<Element<Msg>>,
	pub( crate ) colors:      TabStripColors,
	pub( crate ) layout:      TabLayout,
	pub( crate ) motion:      TabMotion,
}

impl<Msg: Clone + 'static> TabStrip<Msg>
{
	pub fn new( tabs: impl IntoIterator<Item = TabItem> ) -> Self
	{
		Self
		{
			tabs:        tabs.into_iter().collect(),
			selected:    0,
			on_select:   None,
			on_close:    None,
			on_overview: None,
			reorderable: false,
			leading:     Vec::new(),
			after:       Vec::new(),
			trailing:    Vec::new(),
			center:      None,
			colors:      TabStripColors::default(),
			layout:      TabLayout::Desktop,
			motion:      TabMotion::default(),
		}
	}

	pub fn selected( mut self, idx: usize ) -> Self
	{
		self.selected = idx;
		self
	}

	/// Called with the index of the tab pressed.
	pub fn on_select( mut self, f: impl Fn( usize ) -> Msg + 'static ) -> Self
	{
		self.on_select = Some( Arc::new( f ) );
		self
	}

	/// Called with the index of the tab whose close button was pressed.
	pub fn on_close( mut self, f: impl Fn( usize ) -> Msg + 'static ) -> Self
	{
		self.on_close = Some( Arc::new( f ) );
		self
	}

	/// The message the phone bar's counter sends, to show the [`TabOverview`]. Without it the bar has no counter.
	pub fn on_overview( mut self, msg: Msg ) -> Self
	{
		self.on_overview = Some( msg );
		self
	}

	/// Whether the desktop strip's tabs can be dragged into another order; the app forwards the drag to the
	/// [`TabMotion`] and moves the tab [`TabMotion::drag_end`] reports. Dragging a tab selects it. Default: `false`.
	pub fn reorderable( mut self, reorderable: bool ) -> Self
	{
		self.reorderable = reorderable;
		self
	}

	/// A button at the far left, before the tabs; also at the left of the phone bar.
	pub fn leading( mut self, button: impl Into<Element<Msg>> ) -> Self
	{
		self.leading.push( button.into() );
		self
	}

	/// A button right after the last tab, such as a new tab button. Not on the phone bar: the overview's header has those.
	pub fn after_tabs( mut self, button: impl Into<Element<Msg>> ) -> Self
	{
		self.after.push( button.into() );
		self
	}

	/// A button at the far right; also at the right of the phone bar.
	pub fn trailing( mut self, button: impl Into<Element<Msg>> ) -> Self
	{
		self.trailing.push( button.into() );
		self
	}

	/// What the phone bar shows in place of the active tab's icon and title, such as an address field.
	pub fn mobile_center( mut self, center: impl Into<Element<Msg>> ) -> Self
	{
		self.center = Some( center.into() );
		self
	}

	pub fn colors( mut self, colors: TabStripColors ) -> Self
	{
		self.colors = colors;
		self
	}

	pub fn layout( mut self, layout: TabLayout ) -> Self
	{
		self.layout = layout;
		self
	}

	/// The animation state the app keeps; without it the tabs do not animate.
	pub fn motion( mut self, motion: &TabMotion ) -> Self
	{
		self.motion = motion.clone();
		self
	}

	pub fn build( self ) -> Element<Msg>
	{
		match self.layout
		{
			TabLayout::Desktop => desktop::build( self ),
			TabLayout::Mobile  => mobile::build( self ),
		}
	}
}

impl<Msg: Clone + 'static> From<TabStrip<Msg>> for Element<Msg>
{
	fn from( strip: TabStrip<Msg> ) -> Self
	{
		strip.build()
	}
}

/// Create a [`TabStrip`] of `tabs`.
pub fn tab_strip<Msg: Clone + 'static>( tabs: impl IntoIterator<Item = TabItem> ) -> TabStrip<Msg>
{
	TabStrip::new( tabs )
}