The highest tagged major version is
README
¶
Bubblon
Bubblon is a solution for managing nested Bubble Tea models (or views/screens). This is a common use case in TUIs—for example, navigating from a main list to a sublist when an item is selected. The "canonical" way to structure this is with a view-switching model, where you keep track which view you're in (e.g., main or sub) and what item is selected, then render the appropriate model(s) for that view.
By contrast, Bubblon uses a "model stack" architecture, where the controller determines the current model. Instead of bloating a single Model with state for everything, you encapsulate each view in its own tea.Model with its own Update(), View(), and logic. The controller then pushes/pops models on a stack as the user navigates.
Benefits
- 📦 Modular: Each view is self-contained.
- 🔁 Reusability of sub-models.
- 🧠 Easier to reason about, especially when state gets complex.
- 🚫 No new interfaces: Keeps complexity low by avoiding new abstractions.
Example
To run the controller, update the Bubble Tea program initialization from:
mainModel := MainModel.New()
program := tea.NewProgram(mainModel, tea.WithAltScreen())
to:
...
import "github.com/donderom/bubblon"
mainModel := MainModel.New()
controller, err := bubblon.New(mainModel)
program := tea.NewProgram(controller, tea.WithAltScreen())
At any point within the MainModel, you can open a new model by sending a bubblon.Open() command:
func (m MainModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
...
return m, bubblon.Open(SubModel.New())
There are no requirements other than for MainModel and SubModel to implement the tea.Model interface.
To close the current view and return to the previous one, send the bubblon.Close command:
func (m SubModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
...
return m, bubblon.Close
When the SubModel is closed, the MainModel will receive a bubblon.Closed message.
The whole navigation is based on these two commands.
License
Documentation
¶
Overview ¶
Package bubblon enables a model-stack architecture for Bubble Tea apps.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNilModel = errors.New("model cannot be nil")
ErrNilModel is returned when attempting to initialize a Controller with a nil model.
Functions ¶
func Close ¶
Close is a command instructing bubblon to close the current model. A notification to the parent model is sent on closure.
func Cmd ¶
Cmd is a helper function that wraps a tea.Msg as a tea.Cmd. Should be used only for static messages.
Types ¶
type Closed ¶
type Closed struct{}
Closed is a message sent to the parent model indicating that the top model has been closed. The message is not sent if the model is replaced.
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
Controller implements a stack-based navigation model for Bubble Tea apps. It manages a stack of tea.Model instances, where only the top model receives updates and renders.
func New ¶
func New(model tea.Model) (Controller, error)
New creates a new Controller initialized with the given model. Returns an error if the model is nil.
func (Controller) Init ¶
func (c Controller) Init() tea.Cmd
Init initializes the initial model, if one exists.
func (Controller) Update ¶
Update handles incoming messages to update the state and delegate messages to the top model.
func (Controller) View ¶
func (c Controller) View() string
View renders the view of the top model on the stack. Returns an empty string if there is no model.
Source Files