Migrating from bubblezone

bubblezone, by the same author, tracks where parts of a view were drawn so you can tell which one a mouse event landed on. bloom does that job too, as part of laying out the view, and is bubblezone's successor for programs on Bubble Tea v2.

Which one to useCopy Anchor Link

bubblezone v2, github.com/lrstanley/bubblezone/v2, also runs on Bubble Tea v2, and a program that already uses it and builds its view as one string can stay on it. It may not work with Lip Gloss v2's canvas and compositor, though. For a new Bubble Tea v2 program, or one that's adding layers, dialogs, or more mouse handling, use bloom.

What changesCopy Anchor Link

The two libraries work differently. bubblezone wraps parts of your view string in invisible markers, then zone.Scan finds the markers in the final string, records where each one was, and strips them. bloom never sees your view as one string: you build a tree of nodes, bloom places them, and it already knows where each node is.

What you gain:

• Handlers live on the nodes. bloom.Text("save").On(on.Click(m.save)) replaces a zone.Mark in View plus an InBounds check in Update. Most nodes don't need an ID at all.
• One node gets each event. bubblezone reports every zone whose rectangle contains the pointer, and you decide which wins. In bloom, the innermost node with a handler for that kind of event takes it, and layers drawn on top get events first. A modal dialog blocks clicks to what's underneath with no extra checks.
• Nothing to break the markers. There's no zone.Scan step, so MaxWidth, MaxHeight, and anything else that trims a string can't cut a zone in half.
• More kinds of input. Hover, drags, double clicks, and clicks outside a node are built in, along with keyboard focus.
• No global state. There's no manager to start and no background worker to close. Handlers don't need IDs, so there are no prefixes to keep components apart. When you do need an ID, it can be any comparable value: a type such as type itemID int keeps one kind of component's IDs apart from another's, though two instances of the same component still need different values.
• Layout, layers, and motion come with it. bloom also sizes panes, draws dialogs and toasts over the screen, and animates them. See the introduction.

What you give up:

• Your root view becomes a bloom tree. lipgloss.JoinHorizontal and lipgloss.JoinVertical between parts you want to click on become bloom.Row and bloom.Column. Components with a View() string method, and any string, can still be leaves of the tree as they are.
• Newer requirements. bloom needs Bubble Tea v2, Lip Gloss v2, and Go 1.27 or newer.
• A pre-1.0 API. bloom's API may still change in breaking ways before v1.0.0.
• More to learn. bubblezone is a handful of functions. bloom is a layout engine with its own model of slots and sizes; How layout works covers it.

How bubblezone calls map to bloomCopy Anchor Link

Migrate a programCopy Anchor Link

This bubblezone program lists three notes and selects one when it's clicked:

type model struct {
	items    []string
	selected int
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyPressMsg:
		if msg.String() == "q" {
			return m, tea.Quit
		}
	case tea.MouseReleaseMsg:
		if msg.Button != tea.MouseLeft {
			return m, nil
		}
		for i := range m.items {
			if zone.Get(fmt.Sprintf("item-%d", i)).InBounds(msg) {
				m.selected = i
			}
		}
	}
	return m, nil
}

func (m model) View() tea.View {
	rows := make([]string, len(m.items))
	for i, name := range m.items {
		style := item
		if i == m.selected {
			style = selected
		}
		rows[i] = zone.Mark(fmt.Sprintf("item-%d", i), style.Render(name))
	}

	v := tea.NewView(zone.Scan(lipgloss.JoinVertical(lipgloss.Left, rows...)))
	v.AltScreen = true
	v.MouseMode = tea.MouseModeCellMotion
	return v
}

func main() {
	zone.NewGlobal()
	m := model{items: []string{"Groceries", "Ideas", "Reading"}}
	// ...
}

type model struct {
	ui            *bloom.Root
	width, height int
	items         []string
	selected      int
}

func (m *model) Init() tea.Cmd { return m.ui.Init() }

func (m *model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.WindowSizeMsg:
		m.width, m.height = msg.Width, msg.Height
	case tea.KeyPressMsg:
		if msg.String() == "q" {
			return m, tea.Quit
		}
	}
	return m, m.ui.Update(msg)
}

m := &model{ui: bloom.New(), items: []string{"Groceries", "Ideas", "Reading"}}

func (m *model) View() tea.View {
	rows := make([]bloom.Child, len(m.items))
	for i, name := range m.items {
		style := item
		if i == m.selected {
			style = selected
		}
		rows[i] = bloom.Text(name).Style(style).On(on.Click(func() tea.Cmd {
			m.selected = i
			return nil
		}))
	}

	v := m.ui.View(m.width, m.height, bloom.Column(rows...))
	v.AltScreen = true
	v.MouseMode = tea.MouseModeCellMotion
	return v
}

Don't mix the twoCopy Anchor Link

Move a program over in one go rather than running bubblezone and bloom side by side. zone.Scan needs the whole screen as one string, and bloom draws cells and returns a tea.View. bloom also drops bubblezone's markers when it draws text, so a zone.Mark inside a bloom layout never registers a zone.

RelatedCopy Anchor Link

• Mouse events, for every handler and how bloom picks the node that gets an event
• Build your first layout, a tutorial that starts from an empty screen
• Using Bubbles components, for components you used to wrap in zone.Mark
• bubblezone on GitHub