help

Documentation

Overview

Package help renders a toggleable help overlay showing key bindings, modeled on pug's help widget. Pass in a []key.Binding and get back a bordered string that shows key/description columns flowed to fit the available width.

Components that want to contribute their own bindings can implement the Provider interface; the parent collects bindings from the focused child and passes them in via SetBindings before rendering.

Index

• func Compile(groups ...[]key.Binding) []key.Binding
• type Model
  • func New(opts Options) Model
  • func (m Model) Height() int
  • func (m Model) Init() tea.Cmd
  • func (m *Model) SetBindings(b []key.Binding)
  • func (m *Model) SetDimensions(w, h int)
  • func (m Model) ShortView() string
  • func (m Model) Update(_ tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
  • func (m Model) Width() int
• type Options
• type Provider

Functions

func Compile

func Compile(groups ...[]key.Binding) []key.Binding

Compile flattens multiple binding groups into one, removing duplicates. Bindings are considered duplicates when their Keys() match.

Types

type Model

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

Model renders a help overlay. Call SetBindings to change what it shows and SetDimensions on window resize. Visibility is the parent's concern: render the View() string only when help should appear.

func New

func New(opts Options) Model

New constructs a help overlay.

func (Model) Height

func (m Model) Height() int

func (Model) Init

func (m Model) Init() tea.Cmd

func (*Model) SetBindings

func (m *Model) SetBindings(b []key.Binding)

func (*Model) SetDimensions

func (m *Model) SetDimensions(w, h int)

func (Model) ShortView

func (m Model) ShortView() string

ShortView renders the current bindings as a single inline line — "key desc <sep> key desc <sep> ..." — using KeyStyle and DescStyle.

The separator and the space between each key and its description are rendered through DescStyle so that any background color set on DescStyle extends across the whole line with no gaps. When embedding in a colored status bar, give KeyStyle and DescStyle the same Background as the bar.

func (Model) Update

func (m Model) Update(_ tea.Msg) (Model, tea.Cmd)

func (Model) View

func (m Model) View() string

View renders the overlay as a bordered box.

func (Model) Width

func (m Model) Width() int

type Options

type Options struct {
	// Width and Height are the outer dimensions of the overlay, including the
	// border.
	Width, Height int
	// KeyStyle is applied to the key column (left side of each pair).
	KeyStyle lipgloss.Style
	// DescStyle is applied to the description column.
	DescStyle lipgloss.Style
	// Border is the overlay's border. Defaults to lipgloss.NormalBorder().
	Border lipgloss.Border
	// BorderColor colors the border. Defaults to "240" (dim grey).
	BorderColor lipgloss.TerminalColor
	// ColumnSpacer is placed between column-pairs in the overlay. Defaults
	// to "   ".
	ColumnSpacer string
	// ShortSeparator is placed between bindings in ShortView. Defaults to
	// "  •  ".
	ShortSeparator string
}

Options configures a help overlay. Zero-value fields fall back to defaults.

type Provider

type Provider interface {
	HelpBindings() []key.Binding
}

Provider is implemented by components that want to surface extra key bindings in the help overlay when focused.