skeleton

README

Skeleton

Skeleton is a Go library built on top of the Bubble Tea framework designed to simplify the development of multi-tab terminal user interface (TUI) applications.

Caution: This project is under active development and may have breaking changes for a while.

Features

• Multi-tab Support: Easily create and manage multiple tabs in your terminal application, similar to browser tabs.
• Dynamic Widgets: Add and update widgets on the screen, such as battery status, time, or any other information.
• Simple Integration: Build complex TUI applications with a straightforward and modular approach.
• Customizable: You can customize every aspect of the tabs and widgets, including key bindings and appearance.
• Realtime Updates: Updates itself instantly every time the terminal is resized, appearance changes, widgets changes, content changes, etc.
• Responsive Design: Automatically adjusts the layout based on the terminal size.

Tutorial

Skeleton leverages Bubble Tea's architecture to provide a framework for multi-tab TUI applications. This tutorial assumes you have a working knowledge of Go and Bubble Tea.

For a complete example code, you can refer to the source code on GitHub.

Getting Started

First, you'll need to install Skeleton. Use the following command to get it:

go get github.com/termkit/skeleton

Example Usage

Let's walk through an example of how to use Skeleton to create a basic multi-tab application.

1. Define the Models

We'll start by defining a simple model for our tabs. Each tab will be represented by a tinyModel struct:

package main

import (
	"fmt"
	"strings"

	"github.com/termkit/skeleton"
	"github.com/charmbracelet/bubbles/key"
	tea "github.com/charmbracelet/bubbletea"
)

// -----------------------------------------------------------------------------
// Tiny Model
// The Tiny Model is a sub-model for the tabs. It's a simple model that just shows the title of the tab.

// tinyModel is a sub-model for the tabs
type tinyModel struct {
	skeleton *skeleton.Skeleton
	title    string
}

// newTinyModel returns a new tinyModel
func newTinyModel(skeleton *skeleton.Skeleton, title string) *tinyModel {
	return &tinyModel{
		skeleton: skeleton,
		title:    title,
	}
}

func (m tinyModel) Init() tea.Cmd {
	return nil
}
func (m tinyModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	return m, nil
}
func (m tinyModel) View() string {
	verticalCenter := m.skeleton.GetTerminalHeight()/2 - 3
	requiredNewLines := strings.Repeat("\n", verticalCenter)
	return fmt.Sprintf("%s%s | %d x %d", requiredNewLines, m.title, m.skeleton.GetTerminalWidth(), m.skeleton.GetTerminalHeight())
}

2. Set Up the Application

Initialize Skeleton, add pages, and configure widgets:

// -----------------------------------------------------------------------------
// Main Program
func main() {
	s := skeleton.NewSkeleton()

	// Add tabs (pages)
	s.AddPage("first", "First Tab", newTinyModel(s, "First"))
	s.AddPage("second", "Second Tab", newTinyModel(s, "Second"))
	s.AddPage("third", "Third Tab", newTinyModel(s, "Third"))

	// Set up key bindings ( Optional | Defaults: ctrl+left, ctrl+right )
	//To switch next page
	s.KeyMap.SwitchTabRight = key.NewBinding(
		key.WithKeys("shift+right"))

	// To switch previous page
	s.KeyMap.SwitchTabLeft = key.NewBinding(
		key.WithKeys("shift+left"))

	// Add a widget to entire screen
	s.AddWidget("battery", "Battery %92")
	s.AddWidget("time", time.Now().Format("15:04:05"))

	// Update the time widget every second
	go func() {
		time.Sleep(time.Second)
		for {
			s.UpdateWidgetValue("time", time.Now().Format("15:04:05"))
			time.Sleep(time.Second)
		}
	}()

	p := tea.NewProgram(s)
	if err := p.Start(); err != nil {
		panic(err)
	}
}

Understanding the Code

1. Model Definition: tinyModel represents the content of each tab. It uses the Skeleton instance to query terminal dimensions and display information.

2. Application Setup: The main function initializes Skeleton, adds pages, and sets up widgets. The time widget updates every second to reflect the current time.

Skeleton in the Wild

Some programs that use Skeleton in production:

• gama: Manage your GitHub Actions from Terminal with great UI 🧪

Documentation

For more detailed documentation and additional examples, please refer to the Wiki or the Documentation.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

License

Distributed under the GNU GENERAL PUBLIC LICENSE Version 3 or later. See LICENSE for more information.

Contact & Author

Engin Açıkgöz

Stargazers over time

Documentation

Index

• type AddNewWidget
• type AddPage
• type DeletePage
• type DeleteWidget
• type DummyMsg
• type HeaderSizeMsg
• type IAMActivePage
• type Skeleton
  • func NewSkeleton() *Skeleton
  • func (s *Skeleton) AddPage(key string, title string, page tea.Model) *Skeleton
  • func (s *Skeleton) AddWidget(key string, value string) *Skeleton
  • func (s *Skeleton) DeleteAllWidgets() *Skeleton
  • func (s *Skeleton) DeletePage(key string) *Skeleton
  • func (s *Skeleton) DeleteWidget(key string) *Skeleton
  • func (s *Skeleton) GetActivePage() string
  • func (s *Skeleton) GetBorderColor() string
  • func (s *Skeleton) GetPagePosition() lipgloss.Position
  • func (s *Skeleton) GetTerminalHeight() int
  • func (s *Skeleton) GetTerminalViewport() *viewport.Model
  • func (s *Skeleton) GetTerminalWidth() int
  • func (s *Skeleton) GetWidgetBorderColor() string
  • func (s *Skeleton) IAMActivePageCmd() tea.Cmd
  • func (s *Skeleton) Init() tea.Cmd
  • func (s *Skeleton) IsTabsLocked() bool
  • func (s *Skeleton) Listen() tea.Cmd
  • func (s *Skeleton) LockTabs() *Skeleton
  • func (s *Skeleton) SetActivePage(key string) *Skeleton
  • func (s *Skeleton) SetActiveTabBorderColor(color string) *Skeleton
  • func (s *Skeleton) SetActiveTabTextColor(color string) *Skeleton
  • func (s *Skeleton) SetBorderColor(color string) *Skeleton
  • func (s *Skeleton) SetInactiveTabBorderColor(color string) *Skeleton
  • func (s *Skeleton) SetInactiveTabTextColor(color string) *Skeleton
  • func (s *Skeleton) SetPagePosition(position lipgloss.Position) *Skeleton
  • func (s *Skeleton) SetTabLeftPadding(padding int) *Skeleton
  • func (s *Skeleton) SetTabRightPadding(padding int) *Skeleton
  • func (s *Skeleton) SetTerminalViewportHeight(height int)
  • func (s *Skeleton) SetTerminalViewportWidth(width int)
  • func (s *Skeleton) SetWidgetBorderColor(color string) *Skeleton
  • func (s *Skeleton) SetWidgetLeftPadding(padding int) *Skeleton
  • func (s *Skeleton) SetWidgetRightPadding(padding int) *Skeleton
  • func (s *Skeleton) UnlockTabs() *Skeleton
  • func (s *Skeleton) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (s *Skeleton) UpdatePageTitle(key string, title string) *Skeleton
  • func (s *Skeleton) UpdateWidgetValue(key string, value string) *Skeleton
  • func (s *Skeleton) View() string
• type UpdatePageTitle
• type UpdateWidgetContent
• type WidgetSizeMsg

Types

type AddNewWidget

type AddNewWidget struct {
	Key   string
	Value string
}

type AddPage

type AddPage struct {
	// Key is unique key of the page, it is used to identify the page
	Key string

	// Title is the title of the page, it is used to show the title on the header
	Title string

	// Page is the page model, it is used to show the content of the page
	Page tea.Model
}

AddPage adds a new page to the Skeleton.

type DeletePage

type DeletePage struct {
	// Key is unique key of the page, it is used to identify the page
	Key string
}

DeletePage deletes the page by the given key.

type DeleteWidget

type DeleteWidget struct {
	Key string
}

type DummyMsg

type DummyMsg struct{} // To trigger the update

DummyMsg is a dummy message to trigger the update. It used in fast operations that doesn't need to send a message.

type HeaderSizeMsg

type HeaderSizeMsg struct {
	NotEnoughToHandleHeaders bool
}

type IAMActivePage

type IAMActivePage struct{}

IAMActivePage is a message to trigger the update of the active page.

type Skeleton

type Skeleton struct {

	// KeyMap responsible for the key bindings
	KeyMap *keyMap
	// contains filtered or unexported fields
}

Skeleton is a helper for rendering the Skeleton of the terminal.

func NewSkeleton

func NewSkeleton() *Skeleton

NewSkeleton returns a new Skeleton.

func (*Skeleton) AddPage

func (s *Skeleton) AddPage(key string, title string, page tea.Model) *Skeleton

AddPage adds a new page to the Skeleton.

func (*Skeleton) AddWidget

func (s *Skeleton) AddWidget(key string, value string) *Skeleton

AddWidget adds a new widget to the Skeleton.

func (*Skeleton) DeleteAllWidgets

func (s *Skeleton) DeleteAllWidgets() *Skeleton

DeleteAllWidgets deletes all the widgets.

func (*Skeleton) DeletePage

func (s *Skeleton) DeletePage(key string) *Skeleton

DeletePage deletes the page by the given key.

func (*Skeleton) DeleteWidget

func (s *Skeleton) DeleteWidget(key string) *Skeleton

DeleteWidget deletes the Value by the given key.

func (*Skeleton) GetActivePage

func (s *Skeleton) GetActivePage() string

GetActivePage returns the active page key.

func (*Skeleton) GetBorderColor

func (s *Skeleton) GetBorderColor() string

GetBorderColor returns the border color of the Skeleton.

func (*Skeleton) GetPagePosition

func (s *Skeleton) GetPagePosition() lipgloss.Position

GetPagePosition returns the position of the page.

func (*Skeleton) GetTerminalHeight

func (s *Skeleton) GetTerminalHeight() int

GetTerminalHeight returns the height of the terminal.

func (*Skeleton) GetTerminalViewport

func (s *Skeleton) GetTerminalViewport() *viewport.Model

GetTerminalViewport returns the viewport.

func (*Skeleton) GetTerminalWidth

func (s *Skeleton) GetTerminalWidth() int

GetTerminalWidth returns the width of the terminal.

func (*Skeleton) GetWidgetBorderColor

func (s *Skeleton) GetWidgetBorderColor() string

GetWidgetBorderColor returns the border color of the Widget.

func (*Skeleton) IAMActivePageCmd

func (s *Skeleton) IAMActivePageCmd() tea.Cmd

IAMActivePageCmd returns the IAMActivePage command.

func (*Skeleton) Init

func (s *Skeleton) Init() tea.Cmd

func (*Skeleton) IsTabsLocked

func (s *Skeleton) IsTabsLocked() bool

IsTabsLocked returns the tabs (headers) are locked or not.

func (*Skeleton) Listen

func (s *Skeleton) Listen() tea.Cmd

Listen returns the update channel. It listens to the update channel and returns the message. If there is no message, it waits for the message.

func (*Skeleton) LockTabs

func (s *Skeleton) LockTabs() *Skeleton

LockTabs locks the tabs (headers). It prevents switching tabs. It is useful when you want to prevent switching tabs.

func (*Skeleton) SetActivePage

func (s *Skeleton) SetActivePage(key string) *Skeleton

SetActivePage sets the active page by the given key.

func (*Skeleton) SetActiveTabBorderColor

func (s *Skeleton) SetActiveTabBorderColor(color string) *Skeleton

SetActiveTabBorderColor sets the active tab border color of the Skeleton.

func (*Skeleton) SetActiveTabTextColor

func (s *Skeleton) SetActiveTabTextColor(color string) *Skeleton

SetActiveTabTextColor sets the active tab color of the Skeleton.

func (*Skeleton) SetBorderColor

func (s *Skeleton) SetBorderColor(color string) *Skeleton

SetBorderColor sets the border color of the Skeleton.

func (*Skeleton) SetInactiveTabBorderColor

func (s *Skeleton) SetInactiveTabBorderColor(color string) *Skeleton

SetInactiveTabBorderColor sets the idle tab border color of the Skeleton.

func (*Skeleton) SetInactiveTabTextColor

func (s *Skeleton) SetInactiveTabTextColor(color string) *Skeleton

SetInactiveTabTextColor sets the idle tab color of the Skeleton.

func (*Skeleton) SetPagePosition

func (s *Skeleton) SetPagePosition(position lipgloss.Position) *Skeleton

SetPagePosition sets the position of the page.

func (*Skeleton) SetTabLeftPadding

func (s *Skeleton) SetTabLeftPadding(padding int) *Skeleton

SetTabLeftPadding sets the left padding of the Skeleton.

func (*Skeleton) SetTabRightPadding

func (s *Skeleton) SetTabRightPadding(padding int) *Skeleton

SetTabRightPadding sets the right padding of the Skeleton.

func (*Skeleton) SetTerminalViewportHeight

func (s *Skeleton) SetTerminalViewportHeight(height int)

SetTerminalViewportHeight sets the height of the viewport.

func (*Skeleton) SetTerminalViewportWidth

func (s *Skeleton) SetTerminalViewportWidth(width int)

SetTerminalViewportWidth sets the width of the viewport.

func (*Skeleton) SetWidgetBorderColor

func (s *Skeleton) SetWidgetBorderColor(color string) *Skeleton

SetWidgetBorderColor sets the border color of the Widget.

func (*Skeleton) SetWidgetLeftPadding

func (s *Skeleton) SetWidgetLeftPadding(padding int) *Skeleton

SetWidgetLeftPadding sets the left padding of the Skeleton.

func (*Skeleton) SetWidgetRightPadding

func (s *Skeleton) SetWidgetRightPadding(padding int) *Skeleton

SetWidgetRightPadding sets the right padding of the Skeleton.

func (*Skeleton) UnlockTabs

func (s *Skeleton) UnlockTabs() *Skeleton

UnlockTabs unlocks the tabs (headers). It allows switching tabs. It is useful when you want to allow switching tabs.

func (*Skeleton) Update

func (s *Skeleton) Update(msg tea.Msg) (tea.Model, tea.Cmd)

func (*Skeleton) UpdatePageTitle

func (s *Skeleton) UpdatePageTitle(key string, title string) *Skeleton

UpdatePageTitle updates the title of the page by the given key.

func (*Skeleton) UpdateWidgetValue

func (s *Skeleton) UpdateWidgetValue(key string, value string) *Skeleton

UpdateWidgetValue updates the Value content by the given key. Adds the widget if it doesn't exist.

func (*Skeleton) View

func (s *Skeleton) View() string

type UpdatePageTitle

type UpdatePageTitle struct {
	// Key is unique key of the page, it is used to identify the page
	Key string

	// Title is the title of the page, it is used to show the title on the header
	Title string
}

UpdatePageTitle updates the title of the page by the given key.

type UpdateWidgetContent

type UpdateWidgetContent struct {
	Key   string
	Value string
}

type WidgetSizeMsg

type WidgetSizeMsg struct {
	NotEnoughToHandleWidgets bool
}