Trait NavigationProvider 

pub trait NavigationProvider {
    type LevelKey: Eq + Ord + Clone;
    type LevelData;
    type Bar: View;

    // Required methods
    fn parent(&self, current: &Self::LevelKey) -> Option<Self::LevelKey>;
    fn is_ancestor(
        &self,
        ancestor: &Self::LevelKey,
        descendant: &Self::LevelKey,
    ) -> bool;
    fn is_root(&self, key: &Self::LevelKey, context: &Context) -> bool;
    fn fetch_level_data(
        &self,
        key: &Self::LevelKey,
        context: &mut Context,
    ) -> Self::LevelData;
    fn estimate_line_count(
        &self,
        key: &Self::LevelKey,
        data: &Self::LevelData,
    ) -> usize;
    fn create_bar(&self, rect: Rectangle, key: &Self::LevelKey) -> Self::Bar;
    fn bar_key(&self, bar: &Self::Bar) -> Self::LevelKey;
    fn update_bar(
        &self,
        bar: &mut Self::Bar,
        data: &Self::LevelData,
        selected: &Self::LevelKey,
        fonts: &mut Fonts,
    );
    fn update_bar_selection(
        &self,
        bar: &mut Self::Bar,
        selected: &Self::LevelKey,
    );
    fn resize_bar_by(
        &self,
        bar: &mut Self::Bar,
        delta_y: i32,
        fonts: &mut Fonts,
    ) -> i32;
    fn shift_bar(&self, bar: &mut Self::Bar, delta: Point);

    // Provided methods
    fn selected_leaf_key(&self, selected: &Self::LevelKey) -> Self::LevelKey { ... }
    fn leaf_for_bar_traversal(
        &self,
        selected: &Self::LevelKey,
        _context: &Context,
    ) -> Self::LevelKey { ... }
}

Domain adapter for StackNavigationBar.

A NavigationProvider tells the container how to traverse hierarchical levels (e.g. directory parents), and how to populate each bar with pre-fetched data. This trait abstracts the domain-specific logic from the navigation bar’s layout and interaction logic.

Implementation Notes

When implementing resize_bar_by(), ensure the bar respects minimum height constraints (typically SMALL_BAR_HEIGHT - THICKNESS_MEDIUM scaled by DPI). The method should return the actual resize amount after applying constraints.

Required Associated Types

type LevelKey: Eq + Ord + Clone

Key that identifies a level in the stack.

type LevelData

Data needed to render a level.

type Bar: View

Concrete view used to render a level.

Required Methods

fn parent(&self, current: &Self::LevelKey) -> Option<Self::LevelKey>

Returns the parent key, if any.

fn is_ancestor( &self, ancestor: &Self::LevelKey, descendant: &Self::LevelKey, ) -> bool

Returns true if ancestor is an ancestor of descendant.

fn is_root(&self, key: &Self::LevelKey, context: &Context) -> bool

Returns true if the key is the root of the stack.

fn fetch_level_data( &self, key: &Self::LevelKey, context: &mut Context, ) -> Self::LevelData

Fetch the data for a level.

fn estimate_line_count( &self, key: &Self::LevelKey, data: &Self::LevelData, ) -> usize

Estimates how many visual lines (rows) the bar will need to display its content.

This value is used to calculate the vertical height of the bar. Each line corresponds to one row in the visual layout:

• For vertical layouts (e.g., DirectoriesBar), this typically equals the number of items to display since each item occupies one line.
• For horizontal layouts (e.g., CategoryNavigationBar), this should return 1 since all items are arranged horizontally on a single line.

The height formula is:

height = line_count * x_height + (line_count + 1) * padding / 2

Returns

The number of visual lines needed.

Returning 0 indicates that the level has no visible content and allows StackNavigationBar to treat this level as empty (for example, by not inserting a bar for it). Values >= 1 correspond to the number of visual lines that should be allocated for the bar’s content.

fn create_bar(&self, rect: Rectangle, key: &Self::LevelKey) -> Self::Bar

Creates a new empty bar for the given level key.

This method is responsible for instantiating a concrete bar view that will display content for a specific level in the navigation hierarchy. The bar is created with an initial rectangle and is positioned by StackNavigationBar.

The returned bar should be empty or minimally initialized, its content will be populated later via update_bar() once the necessary data is fetched from the domain layer. This separation allows bars to be created before their content is available, enabling flexible reuse and repositioning strategies.

Arguments

• rect - The initial rectangle where the bar will be positioned. This rectangle is computed by StackNavigationBar based on layout metrics and available space. The bar should use this rect as its initial bounds.
• key - The level identifier (e.g., a directory path or category ID) that uniquely identifies which level this bar represents in the hierarchy.

Returns

A new bar view instance initialized with the provided rectangle. The bar’s content should be empty or a placeholder at this point.

Implementation Notes

• The bar’s rectangle must be stored and accessible via the View trait’s rect() and rect_mut() methods.
• Do not fetch or populate content in this method; that happens in update_bar().
• The key parameter is provided for reference but typically stored separately by the domain layer (see bar_key() to retrieve it).
• If the concrete bar type needs additional context (e.g., fonts or device info) during creation, access it from a shared source rather than requiring it as a method parameter.

Example

fn create_bar(&self, rect: Rectangle, key: &Self::LevelKey) -> Self::Bar {
    MyBar::new(rect, key.clone())
}

fn bar_key(&self, bar: &Self::Bar) -> Self::LevelKey

Returns the key that is currently displayed by a bar.

fn update_bar( &self, bar: &mut Self::Bar, data: &Self::LevelData, selected: &Self::LevelKey, fonts: &mut Fonts, )

Update bar content using only fonts (no context borrowing).

fn update_bar_selection(&self, bar: &mut Self::Bar, selected: &Self::LevelKey)

Update bar selection when the content is unchanged.

fn resize_bar_by( &self, bar: &mut Self::Bar, delta_y: i32, fonts: &mut Fonts, ) -> i32

Apply a vertical resize delta to a bar.

This method should mutate the bar’s rectangle and update its content to reflect the new size. The bar must enforce minimum height constraints (typically SMALL_BAR_HEIGHT - THICKNESS_MEDIUM scaled by DPI).

Arguments

• bar - The bar to resize
• delta_y - The vertical resize amount (positive = grow, negative = shrink)
• fonts - Font registry for text rendering calculations

Returns

The actual resize amount applied after enforcing constraints. This may differ from delta_y if minimum/maximum height limits are reached.

Important

Do NOT pre-modify the bar’s rect before calling this method. The provider will handle the entire resize operation, including constraint enforcement.

fn shift_bar(&self, bar: &mut Self::Bar, delta: Point)

Shift a bar by a delta.

Provided Methods

fn selected_leaf_key(&self, selected: &Self::LevelKey) -> Self::LevelKey

Returns the key to consider “selected”.

Some domains want to select the parent when the leaf level is empty.

fn leaf_for_bar_traversal( &self, selected: &Self::LevelKey, _context: &Context, ) -> Self::LevelKey

Returns the starting key for bar traversal.

This may differ from selected when the selected level is empty. For example, if a directory has no subdirectories, this might return the parent directory to start the bar hierarchy from there.

Implementors

impl NavigationProvider for SettingsCategoryProvider

type LevelKey = Category

type LevelData = ()

type Bar = CategoryNavigationBar

impl NavigationProvider for DirectoryNavigationProvider

type LevelKey = PathBuf

type LevelData = BTreeSet<PathBuf>

type Bar = DirectoriesBar