tuikit

README

Terminal UI Kit

This repo contains types, interfaces, and utilities for building terminal user interfaces in Go. It's an opinionated framework that uses charm TUI components and packages for rendering and handling terminal events.

Usage

First, install the package:

go get -u github.com/flowexec/tuikit@latest

You can then use the package in your Go code:

package main

import (
    "context"

    "github.com/flowexec/tuikit"
    "github.com/flowexec/tuikit/views"
)

func main() {
    ctx := context.Background()
    // Define your application metadata
    app := &tuikit.Application{Name: "MyApp"}

    // Create and start the container
    container, err := tuikit.NewContainer(ctx, app)
    if err != nil {
        panic(err)
    }
    if err := container.Start(); err != nil {
        panic(err)
    }
    
    // Create and set your view - the example below used the Markdown view type.
    // There are other view types available in the views package.
    view := views.NewMarkdownView(container.RenderState(), "# Hello, world!")
    if err := container.SetView(view); err != nil {
        panic(err)
    }
    
    // Wait for the container to exit. Before getting here, you can handle events, update the view, etc.
    container.WaitForExit()
}

Also see the sample app for examples of how different views can be used.

Documentation

Index

• type Application
  • func NewApplication(name string, opts ...ApplicationOption) *Application
• type ApplicationOption
  • func WithLoadingMsg(msg string) ApplicationOption
  • func WithState(key, val string) ApplicationOption
  • func WithStateKey(key string) ApplicationOption
  • func WithStateVal(val string) ApplicationOption
  • func WithVersion(version string) ApplicationOption
• type BackHandler
• type Container
  • func NewContainer(ctx context.Context, app *Application, opts ...ContainerOptions) (*Container, error)
  • func (c *Container) ContentHeight() int
  • func (c *Container) ContentWidth() int
  • func (c *Container) CurrentView() View
  • func (c *Container) HandleError(err error)
  • func (c *Container) Height() int
  • func (c *Container) Init() tea.Cmd
  • func (c *Container) NextView() View
  • func (c *Container) PopView() error
  • func (c *Container) PreviousView() View
  • func (c *Container) Program() *Program
  • func (c *Container) Ready() bool
  • func (c *Container) RenderState() *types.RenderState
  • func (c *Container) Send(msg tea.Msg, delay time.Duration)
  • func (c *Container) SetNextView(v View)
  • func (c *Container) SetNotice(notice string, lvl themes.OutputLevel)
  • func (c *Container) SetSendFunc(f func(msg tea.Msg))
  • func (c *Container) SetState(key, val string)
  • func (c *Container) SetStateValue(val string)
  • func (c *Container) SetView(v View) error
  • func (c *Container) Shutdown(finalizers ...func())
  • func (c *Container) SizeSet() bool
  • func (c *Container) Start() error
  • func (c *Container) State() (string, string)
  • func (c *Container) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (c *Container) View() tea.View
  • func (c *Container) WaitForExit()
  • func (c *Container) Width() int
• type ContainerOptions
  • func WithInitialTermSize(width, height int) ContainerOptions
  • func WithInput(in io.Reader) ContainerOptions
  • func WithOutput(out io.Writer) ContainerOptions
  • func WithTheme(theme themes.Theme) ContainerOptions
• type InputCapturer
• type Program
  • func NewProgram(ctx context.Context, model tea.Model, in io.Reader, out io.Writer) *Program
  • func (p *Program) Resume() error
  • func (p *Program) Run() (tea.Model, error)
  • func (p *Program) Send(msg tea.Msg)
  • func (p *Program) SetTeaProgram(program *tea.Program)
  • func (p *Program) Started() bool
  • func (p *Program) Suspend() error
  • func (p *Program) Suspended() bool
• type View

Types

type Application

type Application struct {
	Name    string
	Version string
	// contains filtered or unexported fields
}

func NewApplication

func NewApplication(name string, opts ...ApplicationOption) *Application

type ApplicationOption

type ApplicationOption func(*Application)

func WithLoadingMsg

func WithLoadingMsg(msg string) ApplicationOption

func WithState

func WithState(key, val string) ApplicationOption

func WithStateKey

func WithStateKey(key string) ApplicationOption

func WithStateVal

func WithStateVal(val string) ApplicationOption

func WithVersion

func WithVersion(version string) ApplicationOption

type BackHandler

type BackHandler interface {
	HandleBack() bool
}

BackHandler is an optional interface views can implement to intercept back navigation events before the Container forcefully pops the view stack.

type Container

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

func NewContainer

func NewContainer(
	ctx context.Context,
	app *Application,
	opts ...ContainerOptions,
) (*Container, error)

func (*Container) ContentHeight

func (c *Container) ContentHeight() int

func (*Container) ContentWidth

func (c *Container) ContentWidth() int

func (*Container) CurrentView

func (c *Container) CurrentView() View

func (*Container) HandleError

func (c *Container) HandleError(err error)

func (*Container) Height

func (c *Container) Height() int

func (*Container) Init

func (c *Container) Init() tea.Cmd

func (*Container) NextView

func (c *Container) NextView() View

func (*Container) PopView

func (c *Container) PopView() error

func (*Container) PreviousView

func (c *Container) PreviousView() View

func (*Container) Program

func (c *Container) Program() *Program

func (*Container) Ready

func (c *Container) Ready() bool

func (*Container) RenderState

func (c *Container) RenderState() *types.RenderState

func (*Container) Send

func (c *Container) Send(msg tea.Msg, delay time.Duration)

func (*Container) SetNextView

func (c *Container) SetNextView(v View)

func (*Container) SetNotice

func (c *Container) SetNotice(notice string, lvl themes.OutputLevel)

func (*Container) SetSendFunc

func (c *Container) SetSendFunc(f func(msg tea.Msg))

func (*Container) SetState

func (c *Container) SetState(key, val string)

func (*Container) SetStateValue

func (c *Container) SetStateValue(val string)

func (*Container) SetView

func (c *Container) SetView(v View) error

func (*Container) Shutdown

func (c *Container) Shutdown(finalizers ...func())

func (*Container) SizeSet

func (c *Container) SizeSet() bool

func (*Container) Start

func (c *Container) Start() error

func (*Container) State

func (c *Container) State() (string, string)

func (*Container) Update

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

func (*Container) View

func (c *Container) View() tea.View

func (*Container) WaitForExit

func (c *Container) WaitForExit()

func (*Container) Width

func (c *Container) Width() int

type ContainerOptions

type ContainerOptions func(*Container)

func WithInitialTermSize

func WithInitialTermSize(width, height int) ContainerOptions

func WithInput

func WithInput(in io.Reader) ContainerOptions

func WithOutput

func WithOutput(out io.Writer) ContainerOptions

func WithTheme

func WithTheme(theme themes.Theme) ContainerOptions

type InputCapturer

type InputCapturer interface {
	CapturingInput() bool
}

InputCapturer is an optional interface views can implement to signal that they are actively capturing keyboard input (e.g. a filter field). When CapturingInput returns true, the Container forwards all keys to the view instead of handling them globally.

type Program

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

func NewProgram

func NewProgram(ctx context.Context, model tea.Model, in io.Reader, out io.Writer) *Program

func (*Program) Resume

func (p *Program) Resume() error

func (*Program) Run

func (p *Program) Run() (tea.Model, error)

func (*Program) Send

func (p *Program) Send(msg tea.Msg)

func (*Program) SetTeaProgram

func (p *Program) SetTeaProgram(program *tea.Program)

func (*Program) Started

func (p *Program) Started() bool

func (*Program) Suspend

func (p *Program) Suspend() error

func (*Program) Suspended

func (p *Program) Suspended() bool

type View

type View interface {
	tea.Model

	HelpBindings() []themes.HelpKey
	Type() string
}