feat: introduce vertical scrollbar

Author: nervo

scrollbar/example/example.gif

@@ -0,0 +1,16 @@
+Output example.gif
+
+Require go
+
+Hide
+
+Type@0 "go run main.go" Enter
+Sleep 3s
+
+Show
+
+Space@100ms 100
+Up@100ms 50
+Down@100ms 30
+
+Sleep 3s

scrollbar/example/example.tape

@@ -0,0 +1,97 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/charmbracelet/bubbles/scrollbar"
+	"github.com/charmbracelet/bubbles/viewport"
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+)
+
+func newModel() model {
+	// Viewport
+	vp := viewport.New(0, 0)
+
+	// Scrollbar
+	sb := scrollbar.NewVertical()
+	sb.Style = sb.Style.Border(lipgloss.RoundedBorder(), true)
+
+	return model{
+		viewport:  vp,
+		scrollbar: sb,
+	}
+}
+
+type model struct {
+	content   string
+	viewport  viewport.Model
+	scrollbar tea.Model
+}
+
+func (m model) Init() tea.Cmd {
+	return nil
+}
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	var (
+		cmd  tea.Cmd
+		cmds []tea.Cmd
+	)
+
+	switch msg := msg.(type) {
+	case tea.KeyMsg:
+		switch msg.String() {
+		case "ctrl+c", "q", "esc":
+			return m, tea.Quit
+		case " ":
+			if m.content != "" {
+				m.content += "\n"
+			}
+			m.content += fmt.Sprintf("%02d: Lorem ipsum dolor sit amet, consectetur adipiscing elit.", lipgloss.Height(m.content)-1)
+		}
+	case tea.WindowSizeMsg:
+		// Update viewport size
+		m.viewport.Width = msg.Width - 3
+		m.viewport.Height = msg.Height
+
+		// Update scrollbar height
+		m.scrollbar, cmd = m.scrollbar.Update(scrollbar.HeightMsg(msg.Height))
+		cmds = append(cmds, cmd)
+	}
+
+	m.viewport.SetContent(m.content)
+	m.viewport, cmd = m.viewport.Update(msg)
+	cmds = append(cmds, cmd)
+
+	// Update scrollbar viewport
+	m.scrollbar, cmd = m.scrollbar.Update(m.viewport)
+	cmds = append(cmds, cmd)
+
+	return m, tea.Batch(cmds...)
+}
+
+func (m model) View() string {
+	if m.viewport.TotalLineCount() > m.viewport.VisibleLineCount() {
+		return lipgloss.JoinHorizontal(lipgloss.Left,
+			m.viewport.View(),
+			m.scrollbar.View(),
+		)
+	}
+
+	return m.viewport.View()
+}
+
+func main() {
+	p := tea.NewProgram(
+		newModel(),
+		tea.WithAltScreen(),
+		tea.WithMouseCellMotion(),
+	)
+
+	if _, err := p.Run(); err != nil {
+		fmt.Println("could not run program:", err)
+		os.Exit(1)
+	}
+}

scrollbar/example/main.go

@@ -0,0 +1,25 @@
+package scrollbar
+
+// Msg signals that scrollbar parameters must be updated.
+type Msg struct {
+	Total   int
+	Visible int
+	Offset  int
+}
+
+// HeightMsg signals that scrollbar height must be updated.
+type HeightMsg int
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func max(a, b int) int {
+	if a > b {
+		return a
+	}
+	return b
+}

scrollbar/scrollbar.go

@@ -0,0 +1,73 @@
+package scrollbar
+
+import (
+	"math"
+	"strings"
+
+	"github.com/charmbracelet/bubbles/viewport"
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+)
+
+// NewVertical create a new vertical scrollbar.
+func NewVertical() Vertical {
+	return Vertical{
+		Style:      lipgloss.NewStyle().Width(1),
+		ThumbStyle: lipgloss.NewStyle().SetString("█"),
+		TrackStyle: lipgloss.NewStyle().SetString("░"),
+	}
+}
+
+// Vertical is the base struct for a vertical scrollbar.
+type Vertical struct {
+	Style       lipgloss.Style
+	ThumbStyle  lipgloss.Style
+	TrackStyle  lipgloss.Style
+	height      int
+	thumbHeight int
+	thumbOffset int
+}
+
+// Init initializes the scrollbar model.
+func (m Vertical) Init() tea.Cmd {
+	return nil
+}
+
+// Update updates the scrollbar model.
+func (m Vertical) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	switch msg := msg.(type) {
+	case Msg:
+		m.thumbHeight, m.thumbOffset = m.computeThumb(msg.Total, msg.Visible, msg.Offset)
+	case HeightMsg:
+		m.height = m.computeHeight(int(msg))
+	case viewport.Model:
+		m.thumbHeight, m.thumbOffset = m.computeThumb(msg.TotalLineCount(), msg.VisibleLineCount(), msg.YOffset)
+	}
+
+	return m, nil
+}
+
+func (m Vertical) computeHeight(height int) int {
+	return height - m.Style.GetVerticalFrameSize()
+}
+
+func (m Vertical) computeThumb(total, visible, offset int) (int, int) {
+	ratio := float64(m.height) / float64(total)
+
+	thumbHeight := max(1, int(math.Round(float64(visible)*ratio)))
+	thumbOffset := max(0, min(m.height-thumbHeight, int(math.Round(float64(offset)*ratio))))
+
+	return thumbHeight, thumbOffset
+}
+
+// View renders the scrollbar to a string.
+func (m Vertical) View() string {
+	bar := strings.TrimRight(
+		strings.Repeat(m.TrackStyle.String()+"\n", m.thumbOffset)+
+			strings.Repeat(m.ThumbStyle.String()+"\n", m.thumbHeight)+
+			strings.Repeat(m.TrackStyle.String()+"\n", max(0, m.height-m.thumbOffset-m.thumbHeight)),
+		"\n",
+	)
+
+	return m.Style.Render(bar)
+}

scrollbar/vertical.go

@@ -0,0 +1,55 @@
+package scrollbar
+
+import (
+	tea "github.com/charmbracelet/bubbletea"
+	"testing"
+)
+
+func TestVerticalView(t *testing.T) {
+	tests := []struct {
+		name    string
+		total   int
+		visible int
+		offset  int
+		view    string
+	}{
+		{
+			name:    "ThirdTop",
+			total:   9,
+			visible: 3,
+			offset:  0,
+			view:    "█\n░\n░",
+		},
+		{
+			name:    "ThirdMiddle",
+			total:   9,
+			visible: 3,
+			offset:  3,
+			view:    "░\n█\n░",
+		},
+		{
+			name:    "ThirdBottom",
+			total:   9,
+			visible: 3,
+			offset:  6,
+			view:    "░\n░\n█",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var scrollbar tea.Model
+			scrollbar = NewVertical()
+			scrollbar, _ = scrollbar.Update(HeightMsg(test.visible))
+			scrollbar, _ = scrollbar.Update(Msg{
+				Total:   test.total,
+				Visible: test.visible,
+				Offset:  test.offset,
+			})
+			view := scrollbar.View()
+
+			if view != test.view {
+				t.Errorf("expected:\n%s\ngot:\n%s", test.view, view)
+			}
+		})
+	}
+}