// Package table provides a simple table component for Bubble Tea applications. package table import ( "strings" "charm.land/bubbles/v2/help" "charm.land/bubbles/v2/key" "charm.land/bubbles/v2/viewport" tea "charm.land/bubbletea/v2" "charm.land/lipgloss/v2" "github.com/charmbracelet/x/ansi" ) // Model defines a state for the table widget. type Model struct { KeyMap KeyMap Help help.Model cols []Column rows []Row cursor int colCursor int focus bool styles Styles showHeaders bool viewport viewport.Model start int end int } // Row represents one line in the table. type Row []string // Column defines the table structure. type Column struct { Title string Width int } // KeyMap defines keybindings. It satisfies to the help.KeyMap interface, which // is used to render the help menu. type KeyMap struct { LineUp key.Binding LineDown key.Binding PageUp key.Binding PageDown key.Binding HalfPageUp key.Binding HalfPageDown key.Binding GotoTop key.Binding GotoBottom key.Binding CellLeft key.Binding CellRight key.Binding } // ShortHelp implements the KeyMap interface. func (km KeyMap) ShortHelp() []key.Binding { return []key.Binding{km.LineUp, km.LineDown, km.CellLeft, km.CellRight} } // FullHelp implements the KeyMap interface. func (km KeyMap) FullHelp() [][]key.Binding { return [][]key.Binding{ {km.LineUp, km.LineDown, km.GotoTop, km.GotoBottom}, {km.PageUp, km.PageDown, km.HalfPageUp, km.HalfPageDown}, {km.CellLeft, km.CellRight}, } } // DefaultKeyMap returns a default set of keybindings. func DefaultKeyMap() KeyMap { const spacebar = " " return KeyMap{ LineUp: key.NewBinding( key.WithKeys("up", "k"), key.WithHelp("↑/k", "up"), ), LineDown: key.NewBinding( key.WithKeys("down", "j"), key.WithHelp("↓/j", "down"), ), PageUp: key.NewBinding( key.WithKeys("b", "pgup"), key.WithHelp("b/pgup", "page up"), ), PageDown: key.NewBinding( key.WithKeys("pgdown", spacebar), key.WithHelp("pgdn", "page down"), ), HalfPageUp: key.NewBinding( key.WithKeys("u", "ctrl+u"), key.WithHelp("u", "½ page up"), ), HalfPageDown: key.NewBinding( key.WithKeys("d", "ctrl+d"), key.WithHelp("d", "½ page down"), ), GotoTop: key.NewBinding( key.WithKeys("home", "g", "0"), key.WithHelp("g/home/0", "go to start"), ), GotoBottom: key.NewBinding( key.WithKeys("end", "G"), key.WithHelp("G/end", "go to end"), ), CellLeft: key.NewBinding( key.WithKeys("left", "h"), key.WithHelp("←/h", "left"), ), CellRight: key.NewBinding( key.WithKeys("right", "l"), key.WithHelp("→/l", "right"), ), } } // Styles contains style definitions for this list component. By default, these // values are generated by DefaultStyles. type Styles struct { Header lipgloss.Style Cell lipgloss.Style Selected lipgloss.Style Highlight lipgloss.Style } // DefaultStyles returns a set of default style definitions for this table. func DefaultStyles() Styles { return Styles{ Selected: lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("212")), Header: lipgloss.NewStyle().Bold(true).Padding(0, 1), Cell: lipgloss.NewStyle().Padding(0, 1), Highlight: lipgloss.NewStyle().Background(lipgloss.Color("57")).Foreground(lipgloss.Color("0")), } } // SetStyles sets the table styles. func (m *Model) SetStyles(s Styles) { m.styles = s m.UpdateViewport() } // Option is used to set options in New. For example: // // table := New(WithColumns([]Column{{Title: "ID", Width: 10}})) type Option func(*Model) // New creates a new model for the table widget. func New(opts ...Option) Model { m := Model{ cursor: 0, colCursor: 0, viewport: viewport.New(viewport.WithWidth(0), viewport.WithHeight(20)), //nolint:mnd KeyMap: DefaultKeyMap(), Help: help.New(), styles: DefaultStyles(), showHeaders: true, } for _, opt := range opts { opt(&m) } m.UpdateViewport() return m } // WithColumns sets the table columns (headers). func WithColumns(cols []Column) Option { return func(m *Model) { m.cols = cols } } // WithRows sets the table rows (data). func WithRows(rows []Row) Option { return func(m *Model) { m.rows = rows } } // WithHeight sets the height of the table. func WithHeight(h int) Option { return func(m *Model) { m.viewport.SetHeight(h - lipgloss.Height(m.headersView())) } } // WithWidth sets the width of the table. func WithWidth(w int) Option { return func(m *Model) { m.viewport.SetWidth(w) } } // WithFocused sets the focus state of the table. func WithFocused(f bool) Option { return func(m *Model) { m.focus = f } } // WithStyles sets the table styles. func WithStyles(s Styles) Option { return func(m *Model) { m.styles = s } } // WithKeyMap sets the key map. func WithKeyMap(km KeyMap) Option { return func(m *Model) { m.KeyMap = km } } // WithShowHeaders controls rendering of table headers. func WithShowHeaders(show bool) Option { return func(m *Model) { m.showHeaders = show } } // Update is the Bubble Tea update loop. func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) { if !m.focus { return m, nil } switch msg := msg.(type) { case tea.KeyPressMsg: height := m.viewport.Height() switch { case key.Matches(msg, m.KeyMap.LineUp): m.MoveUp(1) case key.Matches(msg, m.KeyMap.LineDown): m.MoveDown(1) case key.Matches(msg, m.KeyMap.PageUp): m.MoveUp(height) case key.Matches(msg, m.KeyMap.PageDown): m.MoveDown(height) case key.Matches(msg, m.KeyMap.HalfPageUp): m.MoveUp(height / 2) //nolint:mnd case key.Matches(msg, m.KeyMap.HalfPageDown): m.MoveDown(height / 2) //nolint:mnd case key.Matches(msg, m.KeyMap.GotoTop): m.GotoTop() case key.Matches(msg, m.KeyMap.GotoBottom): m.GotoBottom() case key.Matches(msg, m.KeyMap.CellLeft): m.MoveLeft(1) case key.Matches(msg, m.KeyMap.CellRight): m.MoveRight(1) } } return m, nil } // Focused returns the focus state of the table. func (m Model) Focused() bool { return m.focus } // Focus focuses the table, allowing the user to move around the rows and // interact. func (m *Model) Focus() { m.focus = true m.UpdateViewport() } // Blur blurs the table, preventing selection or movement. func (m *Model) Blur() { m.focus = false m.UpdateViewport() } // View renders the component. func (m Model) View() string { headers := m.headersView() if headers == "" { return m.viewport.View() } return headers + "\n" + m.viewport.View() } // HelpView is a helper method for rendering the help menu from the keymap. // Note that this view is not rendered by default and you must call it // manually in your application, where applicable. func (m Model) HelpView() string { return m.Help.View(m.KeyMap) } // UpdateViewport updates the list content based on the previously defined // columns and rows. func (m *Model) UpdateViewport() { renderedRows := make([]string, 0, len(m.rows)) height := m.viewport.Height() // Render only rows from: m.cursor-m.viewport.Height to: m.cursor+m.viewport.Height // Constant runtime, independent of number of rows in a table. // Limits the number of renderedRows to a maximum of 2*m.viewport.Height if m.cursor >= 0 { m.start = clamp(m.cursor-height, 0, m.cursor) } else { m.start = 0 } m.end = clamp(m.cursor+height, m.cursor, len(m.rows)) for i := m.start; i < m.end; i++ { renderedRows = append(renderedRows, m.renderRow(i)) } m.viewport.SetContent( lipgloss.JoinVertical(lipgloss.Left, renderedRows...), ) } // SelectedRow returns the selected row, or nil when the cursor is out of range // and no row is selected. // You can cast it to your own implementation. func (m Model) SelectedRow() Row { if m.cursor < 0 || m.cursor >= len(m.rows) { return nil } return m.rows[m.cursor] } // Rows returns the current rows. func (m Model) Rows() []Row { return m.rows } // Columns returns the current columns. func (m Model) Columns() []Column { return m.cols } // SetRows sets a new rows state. func (m *Model) SetRows(r []Row) { m.rows = r m.UpdateViewport() } // SetColumns sets a new columns state. func (m *Model) SetColumns(c []Column) { m.cols = c m.UpdateViewport() } // SetWidth sets the width of the viewport of the table. func (m *Model) SetWidth(w int) { m.viewport.SetWidth(w) m.UpdateViewport() } // SetHeight sets the height of the viewport of the table. func (m *Model) SetHeight(h int) { m.viewport.SetHeight(h - lipgloss.Height(m.headersView())) m.UpdateViewport() } // Height returns the viewport height of the table. func (m Model) Height() int { return m.viewport.Height() } // Width returns the viewport width of the table. func (m Model) Width() int { return m.viewport.Width() } // Cursor returns the index of the selected row. func (m Model) Cursor() int { return m.cursor } // ColumnCursor returns the index of the selected column. func (m Model) ColumnCursor() int { return m.colCursor } // SetCursor sets the cursor position in the table. func (m *Model) SetCursor(n int) { m.cursor = clamp(n, 0, len(m.rows)-1) m.UpdateViewport() } // SetColumnCursor sets the column cursor position in the table. func (m *Model) SetColumnCursor(n int) { m.colCursor = clamp(n, 0, len(m.cols)-1) m.UpdateViewport() } // MoveUp moves the selection up by any number of rows. // It can not go above the first row. func (m *Model) MoveUp(n int) { m.cursor = clamp(m.cursor-n, 0, len(m.rows)-1) yOffset := m.viewport.YOffset() height := m.viewport.Height() switch { case m.start == 0: m.viewport.SetYOffset(clamp(yOffset, 0, m.cursor)) case m.start < height: m.viewport.SetYOffset(clamp(clamp(yOffset+n, 0, m.cursor), 0, height)) case yOffset >= 1: m.viewport.SetYOffset(clamp(yOffset+n, 1, height)) } m.UpdateViewport() } // MoveDown moves the selection down by any number of rows. // It can not go below the last row. func (m *Model) MoveDown(n int) { m.cursor = clamp(m.cursor+n, 0, len(m.rows)-1) m.UpdateViewport() yOffset := m.viewport.YOffset() height := m.viewport.Height() switch { case m.end == len(m.rows) && yOffset > 0: m.viewport.SetYOffset(clamp(yOffset-n, 1, height)) case m.cursor > (m.end-m.start)/2 && yOffset > 0: m.viewport.SetYOffset(clamp(yOffset-n, 1, m.cursor)) case yOffset > 1: case m.cursor > yOffset+height-1: m.viewport.SetYOffset(clamp(yOffset+1, 0, 1)) } } // MoveLeft moves the column selection left by n columns. func (m *Model) MoveLeft(n int) { m.colCursor = clamp(m.colCursor-n, 0, len(m.cols)-1) m.UpdateViewport() } // MoveRight moves the column selection right by n columns. func (m *Model) MoveRight(n int) { m.colCursor = clamp(m.colCursor+n, 0, len(m.cols)-1) m.UpdateViewport() } // GotoTop moves the selection to the first row. func (m *Model) GotoTop() { m.MoveUp(m.cursor) } // GotoBottom moves the selection to the last row. func (m *Model) GotoBottom() { m.MoveDown(len(m.rows)) } // FromValues create the table rows from a simple string. It uses `\n` by // default for getting all the rows and the given separator for the fields on // each row. func (m *Model) FromValues(value, separator string) { rows := []Row{} for _, line := range strings.Split(value, "\n") { r := Row{} for _, field := range strings.Split(line, separator) { r = append(r, field) } rows = append(rows, r) } m.SetRows(rows) } func (m Model) headersView() string { if !m.showHeaders { return "" } s := make([]string, 0, len(m.cols)) for _, col := range m.cols { if col.Width <= 0 { continue } style := lipgloss.NewStyle().Width(col.Width).MaxWidth(col.Width).Inline(true) renderedCell := style.Render(ansi.Truncate(col.Title, col.Width, "…")) s = append(s, m.styles.Header.Render(renderedCell)) } return lipgloss.JoinHorizontal(lipgloss.Top, addSpacing(s)...) } func (m *Model) renderRow(r int) string { highlightRow := r == m.cursor rowStyle := m.styles.Cell if highlightRow { rowStyle = m.styles.Highlight } s := make([]string, 0, len(m.cols)) for i, value := range m.rows[r] { if m.cols[i].Width <= 0 { continue } style := rowStyle if highlightRow && i == m.colCursor { style = m.styles.Selected } style = style.Width(m.cols[i].Width).MaxWidth(m.cols[i].Width).Inline(true) renderedCell := style.Render(ansi.Truncate(value, m.cols[i].Width, "…")) s = append(s, renderedCell) } if highlightRow { return lipgloss.JoinHorizontal(lipgloss.Top, addSpacingStyled(s, rowStyle)...) } return lipgloss.JoinHorizontal(lipgloss.Top, addSpacing(s)...) } func clamp(v, low, high int) int { return min(max(v, low), high) } func addSpacing(cells []string) []string { if len(cells) <= 1 { return cells } spaced := make([]string, 0, len(cells)*2-1) for i, cell := range cells { if i > 0 { spaced = append(spaced, " ") } spaced = append(spaced, cell) } return spaced } func addSpacingStyled(cells []string, style lipgloss.Style) []string { if len(cells) <= 1 { return cells } spaced := make([]string, 0, len(cells)*2-1) for i, cell := range cells { if i > 0 { spaced = append(spaced, style.Padding(0, 0).Render(" ")) } spaced = append(spaced, cell) } return spaced }