soda

README

🥤 Soda

Framework for building TUI apps based on the bubbletea.

It automatically handles state management and general layout, so that you can focus on app functionality rather than fighting with TTY 🤕🥊🖥️

[!WARNING] Work in progress.

Install

go get github.com/tuiphi/soda

Examples

Take a look at the examples folder

Libraries to use with Soda

• Cans: Common Soda component-like states such as text inputs, file picker, viewports and so on.
• Bubbles: A library of common UI components for Bubble Tea.

Why?

I write TUI apps a lot. And after some trial and error I came up with the structure that suits me the best. I've been copy-pasting it for my projects again and again, so I decided to create a separate package for it so that others can benefit from it too.

Documentation

Index

• func Back() tea.Msg
• func BackN(n int) tea.Cmd
• func BackToRoot() tea.Msg
• func Notify(message string) tea.Cmd
• func NotifyWithDuration(message string, duration time.Duration) tea.Cmd
• func PushState(state State) tea.Cmd
• func PushTempState(state State) tea.Cmd
• func Redraw() tea.Msg
• func SendError(err error) tea.Cmd
• func Wrap(supplier func() tea.Cmd) tea.Cmd
• type KeyMap
  • func DefaultKeyMap() KeyMap
  • func (k KeyMap) FullHelp() [][]key.Binding
  • func (k KeyMap) ShortHelp() []key.Binding
• type Layout
  • func NewLayout() Layout
• type Model
  • func New(state State, options ...Option) *Model
  • func (m *Model) Init() tea.Cmd
  • func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (m *Model) View() string
• type OnError
• type Option
  • func WithDefaultLayout(layout Layout) Option
  • func WithKeyMap(keyMap KeyMap) Option
  • func WithMinSize(size Size) Option
  • func WithOnError(onError OnError) Option
  • func WithShowFooter(show bool) Option
  • func WithShowHeader(show bool) Option
  • func WithSpinner(spinner spinner.Spinner) Option
  • func WithStyles(styles Styles) Option
• type Size
  • func (s Size) SplitHorizontal(leftRatio float64) (Size, Size)
  • func (s Size) SplitVertical(topRatio float64) (Size, Size)
  • func (s Size) String() string
• type State
• type Styles
  • func DefaultStyles() Styles

Functions

func Back

func Back() tea.Msg

Back to the previous state

func BackN

func BackN(n int) tea.Cmd

BackN traverses the history N states back

func BackToRoot

func BackToRoot() tea.Msg

BackToRoot traverses to the first (initial) State in the history

func Notify

func Notify(message string) tea.Cmd

Notify sends a notification with the default time.Duration

func NotifyWithDuration

func NotifyWithDuration(message string, duration time.Duration) tea.Cmd

NotifyWithDuration sends a notification with the given time.Duration ignoring the default

func PushState

func PushState(state State) tea.Cmd

PushState will push a new State

func PushTempState

func PushTempState(state State) tea.Cmd

PushTempState will push a new State that won't be saved into history

func Redraw

func Redraw() tea.Msg

func SendError

func SendError(err error) tea.Cmd

func Wrap

func Wrap(supplier func() tea.Cmd) tea.Cmd

Types

type KeyMap

type KeyMap struct {
	Back,
	ForceQuit,
	Quit,
	ShowHelp key.Binding
}

func DefaultKeyMap

func DefaultKeyMap() KeyMap

func (KeyMap) FullHelp

func (k KeyMap) FullHelp() [][]key.Binding

func (KeyMap) ShortHelp

func (k KeyMap) ShortHelp() []key.Binding

type Layout

type Layout struct {
	Horizontal, Vertical lipgloss.Position
}

func NewLayout

func NewLayout() Layout

type Model

type Model struct {
	// contains filtered or unexported fields
}

func New

func New(state State, options ...Option) *Model

func (*Model) Init

func (m *Model) Init() tea.Cmd

func (*Model) Update

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

func (*Model) View

func (m *Model) View() string

type OnError

type OnError func(err error) tea.Cmd

OnError is the function that is called when any error occurs.

type Option

type Option func(*Model)

func WithDefaultLayout

func WithDefaultLayout(layout Layout) Option

func WithKeyMap

func WithKeyMap(keyMap KeyMap) Option

func WithMinSize

func WithMinSize(size Size) Option

func WithOnError

func WithOnError(onError OnError) Option

func WithShowFooter

func WithShowFooter(show bool) Option

func WithShowHeader

func WithShowHeader(show bool) Option

func WithSpinner

func WithSpinner(spinner spinner.Spinner) Option

func WithStyles

func WithStyles(styles Styles) Option

type Size

type Size struct {
	Width, Height int
}

func (Size) SplitHorizontal

func (s Size) SplitHorizontal(leftRatio float64) (Size, Size)

func (Size) SplitVertical

func (s Size) SplitVertical(topRatio float64) (Size, Size)

func (Size) String

func (s Size) String() string

type State

type State interface {
	// Destroy is called when the state is destroyed
	Destroy()

	// Focused state will ask Model to ignore its KeyMap.
	// For example, pass "?" as tea.KeyMsg to the State instead of handling it by the Model (show help)
	Focused() bool

	// SetSize sets State's size.
	// The given Size is the Size of the terminal minus header and footer
	SetSize(size Size) tea.Cmd

	// Title of the State
	Title() string

	// Subtitle is shown below the Title
	Subtitle() string

	// Layout specifies a custom Layout for the state,
	// that will override the default one if the override is set to true
	Layout() (layout Layout, override bool)

	// Status is shown right to the Title
	Status() string

	// KeyMap of the State
	KeyMap() help.KeyMap

	// Init is the first function that will be called. It returns an optional
	// initial command. To not perform an initial command return nil.
	// This function is also called when the State is being popped out from the history
	Init(ctx context.Context) tea.Cmd

	// Update is called when a message is received. Use it to inspect messages
	// and, in response, update the model and/or send a command.
	Update(ctx context.Context, msg tea.Msg) tea.Cmd

	// View renders the State's UI, which is just a string. The view is
	// rendered after every Update.
	View(layout Layout) string
}

type Styles

type Styles struct {
	Global,
	Title,
	Header,
	Subtitle,
	Status,
	Spinner,
	Notification,
	Footer lipgloss.Style
}

func DefaultStyles

func DefaultStyles() Styles