feat: tree bubble #639

dlvhdr · 2024-10-15T16:07:59Z

Introduces a tree bubble for TUIs that require a tree like model with expand/collapse/select functionality.

Screen.Recording.2024-10-25.at.17.31.24.mov

Intended Interactions

All the viewport scrolling methods
expand / collapse
select
later on - filter which will show the tree of matching items

API

Use lipgloss.Tree for the rendering
Expose SelectedNode()
Expose SetSelectedNode()
Tree items
- Have a YOffset that represents their vertical position in the tree
- Will expose their YOffset in a getter so users can scroll to a node
- Will be useful if put inside a viewport
Expose a node's depth in a getter
- so users can style a node based on its depth
- should be done in lipgloss?

Example Usage

See charmbracelet/bubbletea#1190

Closes #233.

tree/tree.go

dlvhdr · 2024-10-21T21:52:32Z

tree/tree.go

+// IsSelected returns whether this item is selected.
+func (t *Node) IsSelected() bool {
+	return t.yOffset == t.opts.treeYOffset
+}
+
+// Depth returns the depth of the node in the tree.
+func (t *Node) Depth() int {
+	return t.depth
+}
+
+// Size returns the number of nodes in the tree.
+// Note that if a child isn't open, its size is 1
+func (t *Node) Size() int {
+	return t.size
+}
+
+// YOffset returns the vertical offset of the Node
+func (t *Node) YOffset() int {
+	return t.yOffset
+}


These can be used to allow for more flexible styling.
I found the StyleFunc of lipgloss.Tree doesn't support some stuff I want, like appending a symbol to the end of each item at the same indentation to the right of it. Maybe there are more use cases.

dlvhdr · 2024-10-21T21:53:38Z

tree/tree.go

+}
+
+// Used to print the Node's tree
+// TODO: Value is not called on the root node, so we need to repeat the open/closed character


Here I found I needed to implement the String() func to repeat the open/close character logic because the Value() func isn't called on the root. Maybe this is an easy fix in lipgloss.

dlvhdr · 2024-10-21T21:54:54Z

tree/tree.go

+func (t *Node) GivenValue() any {
+	return t.value
+}


This was helpful in the TOC example I think. I found that the tree "swallows" my values and I can't read them again. This forces the user to save them before passing to the tree, which is just duplication and not the most ergonomic API. The name is confusing though given the Value() func also exists due to the Node interface from lipgloss.
A ValueFunc, similar to the StyleFunc could also solve this, as I believe that was my usecase.

dlvhdr · 2024-10-21T21:55:30Z

tree/tree.go

+func (t *Node) Children() ltree.Children {
+	return t.tree.Children()
+}


This exposes lipgloss as it has to return lipgloss.Children since that's the interface

tree/tree.go

dlvhdr · 2024-11-16T19:04:31Z

update: starting to take shape when used inside https://github.com/dlvhdr/diffnav

caarlos0

this looks great! would be awesome to add an example as well

tree/node.go

wjam · 2024-12-13T13:15:04Z

I've just been playing with this PR locally and wondered whether it'd be possible to configure the open/closed character per node? The idea I had was a file tree where the closed character for a directory would be a closed folder and the open character would be an open folder.

dlvhdr · 2025-03-29T17:00:17Z

hey guys :) any update on this?

bashbunni · 2025-04-01T02:02:34Z

Hey @dlvhdr sorry for the delay on this. We're going to spend some energy cleaning up bubbles before v2, so rest assured this will be merged soon

vimkim · 2025-04-05T14:40:01Z

This looks awesome! This will give better interactivity in its core essence. I think I'll make a lot of TUIs if this gets accepted. Thanks everyone for their efforts for making the SW world a better place!

andreynering

Hey @dlvhdr,

This looks pretty solid, overall!

Some comments:

Can you rebase with v2-exp and squash into a minimal number of commits? (Can be a single commit)
Is it easy enough to write some tests for this package?
Ensure CI is green (lint included)
- You might need to temporarily pin the last commit from charmbracelet/lipgloss#446. Once merged, we'd pin from v2-exp
I made a couple of comments below

andreynering · 2025-04-10T18:09:56Z

tree/tree.go

+	// ScrollOff is the minimal number of lines to keep visible above and below the selected node.
+	ScrollOff int
+	// OpenCharacter is the character used to represent an open node.
+	OpenCharacter string
+	// ClosedCharacter is the character used to represent a closed node.
+	ClosedCharacter string
+	// CursorCharacter is the character used to represent the cursor.
+	CursorCharacter string
+	// KeyMap encodes the keybindings recognized by the widget.
+	KeyMap KeyMap


I believe that in general, we'd like to avoid having public fields here as much as possible. So these keys like OpenCharacter and ClosedCharacter should be made private and additional Set* functions (SetOpenCharacter) should be implemented.

Am I right? @bashbunni @meowgorithm

Yeah, spot on. That will save is from having to change the API down the road.

tree/tree.go

andreynering · 2025-04-14T18:19:07Z

tree/tree.go

+	// KeyMap encodes the keybindings recognized by the widget.
+	KeyMap KeyMap
+	// styles sets the styling for the tree
+	styles Styles
+	Help   help.Model


Can you move these two public fields (KeyMap and Help) to the top of the list, and add an empty line after to separate from the rest? The table.Table model also does this.

andreynering · 2025-04-14T18:21:26Z

tree/tree.go

+	AdditionalShortHelpKeys func() []key.Binding
+	AdditionalFullHelpKeys  func() []key.Binding


I feel that these two should also be private with Set* functions.

I've changed these, but just noted that these are public fields in the list component.
Let me know if you want me to revert / change the list as well.

I still prefer to keep them private. It may have been by mistake that these got public on the other package.

andreynering · 2025-04-14T18:23:20Z

go.mod

+	golang.org/x/text v0.23.0 // indirect
 )
+
+replace github.com/charmbracelet/lipgloss/v2 v2.0.0-beta.1 => ../lipgloss


OK, I got that it's not possible to pin from your branch (as I asked) because it lives in your private fork.

It's fine to keep as is for now, and I can manually pin to the branch commit once I merge charmbracelet/lipgloss#446

andreynering

Awesome work! 👏 👏 👏

Note that we're targeting v2.1.0 for this feature, so we're going to wait for v2.0.0 to be released before we merge your PRs.

dlvhdr · 2025-04-22T18:18:09Z

Cool :) thanks for the reviews!

ossenthusiast · 2025-08-22T23:17:38Z

@andreynering @dlvhdr any update on this?

andreynering · 2025-08-23T14:11:00Z

@ossenthusiast See #639 (review)

ossenthusiast · 2025-11-20T15:39:28Z

@andreynering any updates?

dlvhdr · 2025-11-20T16:43:11Z

I've just rebased the pr, it's ready for review

andreynering · 2025-11-21T13:50:59Z

@ossenthusiast As I said above, we're targeting v2.1.0 to ship this.

We're already on a Release Candidate for v2.0.0, so the final release is near! Once released, we can do a final review and merge this.

dlvhdr force-pushed the dlvhdr/tree-bubble branch from e32c664 to 0addf7c Compare October 17, 2024 14:39

dlvhdr commented Oct 21, 2024

View reviewed changes

meowgorithm reviewed Oct 24, 2024

View reviewed changes

tree/tree.go Outdated Show resolved Hide resolved

dlvhdr mentioned this pull request Nov 23, 2024

feat(tree): support width and indenter styling charmbracelet/lipgloss#446

Merged

meowgorithm mentioned this pull request Dec 3, 2024

Feature request: Tree model #233

Open

caarlos0 reviewed Dec 3, 2024

View reviewed changes

tree/node.go Outdated Show resolved Hide resolved

tree/node.go Outdated Show resolved Hide resolved

dlvhdr force-pushed the dlvhdr/tree-bubble branch from 021d11d to dbf0223 Compare December 5, 2024 21:41

dlvhdr marked this pull request as ready for review December 5, 2024 21:42

dlvhdr requested a review from bashbunni as a code owner December 5, 2024 21:42

caarlos0 approved these changes Jan 6, 2025

View reviewed changes

bashbunni added the enhancement New feature or request label Jan 23, 2025

bashbunni added this to the new bubbles milestone Jan 23, 2025

bashbunni added the v2 label Mar 31, 2025

dlvhdr mentioned this pull request Apr 5, 2025

Make directory trees collapsible dlvhdr/diffnav#16

Open

andreynering mentioned this pull request Apr 10, 2025

feat(examples): tree charmbracelet/bubbletea#1190

Open

andreynering reviewed Apr 10, 2025

View reviewed changes

feat: tree bubble

46b545e

dlvhdr changed the base branch from master to v2-exp April 12, 2025 14:11

dlvhdr force-pushed the dlvhdr/tree-bubble branch from dbf0223 to 46b545e Compare April 12, 2025 14:12

andreynering reviewed Apr 14, 2025

View reviewed changes

bashbunni modified the milestones: new bubbles, v2.1.0 Apr 14, 2025

dlvhdr added 2 commits April 18, 2025 13:31

refactor

5a6ec72

test: add basic tests

1922694

andreynering approved these changes Apr 22, 2025

View reviewed changes

dlvhdr force-pushed the dlvhdr/tree-bubble branch 3 times, most recently from 72d7eaa to d3621ae Compare November 19, 2025 19:03

dlvhdr mentioned this pull request Jan 3, 2026

feat: fetch all/more reviewers + show “suggested” (code owner) reviewers too dlvhdr/gh-dash#728

Merged

dlvhdr added 5 commits January 23, 2026 15:05

Merge branch 'v2-exp' into dlvhdr/tree-bubble

156d3b1

Merge branch 'v2-exp' into dlvhdr/tree-bubble

3d333f4

Merge branch 'v2-exp' into dlvhdr/tree-bubble

95d58fe

fix: select keybind

e0192f9

fix: nil edge cases

1557de0

dlvhdr force-pushed the dlvhdr/tree-bubble branch from d3621ae to 1557de0 Compare January 23, 2026 13:08

fix: prevent extra help menu spacing and expose viewport scroll

1b666e8

		AdditionalShortHelpKeys func() []key.Binding
		AdditionalFullHelpKeys func() []key.Binding

feat: tree bubble #639

Are you sure you want to change the base?

feat: tree bubble #639

Conversation

dlvhdr commented Oct 15, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Intended Interactions

API

Example Usage

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlvhdr Oct 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlvhdr Oct 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlvhdr Oct 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dlvhdr commented Nov 16, 2024

Uh oh!

caarlos0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

wjam commented Dec 13, 2024

Uh oh!

dlvhdr commented Mar 29, 2025

Uh oh!

bashbunni commented Apr 1, 2025

Uh oh!

vimkim commented Apr 5, 2025

Uh oh!

andreynering left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreynering left a comment

Choose a reason for hiding this comment

Uh oh!

dlvhdr commented Apr 22, 2025

Uh oh!

ossenthusiast commented Aug 22, 2025

Uh oh!

andreynering commented Aug 23, 2025

Uh oh!

ossenthusiast commented Nov 20, 2025

Uh oh!

dlvhdr commented Nov 20, 2025

Uh oh!

andreynering commented Nov 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

dlvhdr commented Oct 15, 2024 •

edited

Loading

dlvhdr Oct 21, 2024 •

edited

Loading

dlvhdr Oct 21, 2024 •

edited

Loading

dlvhdr Oct 21, 2024 •

edited

Loading