src/gui_elements/paginator.py

import streamlit as st

def paginator(items, session_state_key):
    """
    Creates a reusable paginator component for a list of items.

    Args:
        items (list): The list of items to paginate through.
        session_state_key (str): A unique key for storing the current index in 
                                 st.session_state.
    
    Returns:
        Any: The currently selected item from the list.
    """
    list_length = len(items)
    
    # Initialize the session state for the current index if it doesn't exist.
    if session_state_key not in st.session_state:
        st.session_state[session_state_key] = 0

    def next_item():
        """Increments the index, wrapping around to the start if it reaches the end."""
        if list_length > 0:
            st.session_state[session_state_key] = (st.session_state[session_state_key] + 1) % list_length

    def prev_item():
        """Decrements the index, wrapping around to the end if it goes below zero."""
        if list_length > 0:
            st.session_state[session_state_key] = (st.session_state[session_state_key] - 1 + list_length) % list_length

    # Create the navigation columns.
    col1, col2, col3 = st.columns([2, 3, 2])

    with col1:
        st.button("⬅️ Previous", on_click=prev_item, use_container_width=True, disabled=(list_length <= 1))

    # Display the current position and the popover for jumping to a specific item.
    with col2:
        if list_length > 0:
            current_num = st.session_state[session_state_key] + 1
            
            popover = st.popover(f"Item {current_num} of {list_length}", use_container_width=True)

            with popover:
                st.markdown("Jump to a specific item:")
                target_index_input = st.number_input(
                    "Item Number",
                    min_value=1,
                    max_value=list_length,
                    value=current_num,
                    step=1,
                    label_visibility="collapsed"
                )
                if st.button("Go"):
                    st.session_state[session_state_key] = target_index_input - 1
                    st.rerun()
        else:
            st.text("No items to display")

    # "Next" button in the third column.
    with col3:
        st.button("Next ➡️", on_click=next_item, use_container_width=True, disabled=(list_length <= 1))

    # Return the currently selected item.
    if list_length > 0:
        return st.session_state[session_state_key]
    else:
        return None