bubblehelp

README

bubblehelp

A manager to render, contextualize and manage BubbleTea (https://github.com/charmbracelet/bubbletea) keybinds globally

import "github.com/halsten-dev/bubblehelp"

Introduction

When working on a complex application in the terminal, it's important to have a good way of managing multiple contexts with different keybinds, same keys but different outcome, and so on.

I was facing troubles, when trying to manage dynamic keybinds and on top of that the need of rendering help. The BubbleTea library is amazing, but it lack something to manage the keybinds well.

That's why I've created bubblehelp. It's just a coat of quality of life to help you write contextualized TUI application with complex ever-changing help for your users.

Take a look at the example and let your imagination do the rest.

Need help

Do not hesitate to create an issue if you need any kind of help about bubblehelp.

License

MIT License

Copyright (c) 2025 Lionel Leeser

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Overview

Package bubblehelp is a manager to help render, contextualize and manage keybinds for bubbletea.

Index

• Variables
• func Init()
• func IsKeybindVisible(keybind key.Binding) bool
• func RegisterContext(context KeymapContext, keymap *Keymap)
• func SetDefaultStyle(style Style)
• func SetKeybindVisible(keybind key.Binding, visible bool)
• func SwitchContext(context KeymapContext)
• func SwitchToPreviousContext()
• func UpdateKeybindHelpDesc(keybind key.Binding, desc string)
• func View(width int) string
• func ViewAll(keymap *Keymap, width int) string
• func ViewEssential(keymap *Keymap, width int) string
• type Key
  • func (k *Key) GetHelpDesc() string
• type Keymap
  • func GetCurrentContextKeymap() *Keymap
  • func NewKeymap(showAllColCount int) *Keymap
  • func (k *Keymap) AllBindings() []Key
  • func (k *Keymap) EssentialBindings() []Key
  • func (k *Keymap) NewKeyBinding(binding key.Binding, essential bool)
  • func (k *Keymap) Reset()
  • func (k *Keymap) SetHelpDesc(keybind key.Binding, desc string)
• type KeymapContext
• type Style

Variables

var (
	// CurrentContext holds the current context identifier.
	CurrentContext KeymapContext

	// Contexts map of single every registered contexts.
	Contexts map[KeymapContext]*Keymap

	// ShowAll is the flag to define whether it's the full or short help that will be rendered.
	ShowAll bool
)

Functions

func Init

func Init()

Init is the first function that needs to be called in the start of the app.

func IsKeybindVisible

func IsKeybindVisible(keybind key.Binding) bool

IsKeybindVisible returns the current visibility of a Keybind. If the Keybind do not exist in the current context, returns false.

func RegisterContext

func RegisterContext(context KeymapContext, keymap *Keymap)

RegisterContext allows to register a new Keymap context and link it with the given identifier.

func SetDefaultStyle

func SetDefaultStyle(style Style)

func SetKeybindVisible

func SetKeybindVisible(keybind key.Binding, visible bool)

SetKeybindVisible allows to set keybinds visibility in the current Keymap context.

func SwitchContext

func SwitchContext(context KeymapContext)

SwitchContext take care of properly changing context. Resets the current context before switching.

func SwitchToPreviousContext

func SwitchToPreviousContext()

func UpdateKeybindHelpDesc

func UpdateKeybindHelpDesc(keybind key.Binding, desc string)

UpdateKeybindHelpDesc allows to temporary change the help description for a keybind in the current Keymap context.

func View

func View(width int) string

View is the main render function of bubblehelp. Take the ShowAll flag into account to render full or short help.

func ViewAll

func ViewAll(keymap *Keymap, width int) string

ViewAll is the full help render function, can be called directly.

func ViewEssential

func ViewEssential(keymap *Keymap, width int) string

ViewEssential is the short help render function, can be called directly

Types

type Key

type Key struct {
	Binding        key.Binding
	Essential      bool
	CustomHelpDesc string
	Visible        bool
}

Key describes a single keybind in bubblehelp.

func (*Key) GetHelpDesc

func (k *Key) GetHelpDesc() string

GetHelpDesc returns the current help description for the Key. Returns the temporary CustomHelpDesc first.

type Keymap

type Keymap struct {
	Bindings           []Key
	ShowAllColumnCount int
	Style              Style
}

Keymap describes a keymap context inside bubblehelp. Each context can have its own Style definition

func GetCurrentContextKeymap

func GetCurrentContextKeymap() *Keymap

GetCurrentContextKeymap returns a pointer on the current Keymap context.

func NewKeymap

func NewKeymap(showAllColCount int) *Keymap

NewKeymap helps initialize a new context with default style and given column count for full help rendering. showAllColCount parameters allows definition of the columns of the full help rendering.

func (*Keymap) AllBindings

func (k *Keymap) AllBindings() []Key

AllBindings returns every single binding of the Keymap context.

func (*Keymap) EssentialBindings

func (k *Keymap) EssentialBindings() []Key

EssentialBindings returns the slice of all essential binding of the Keymap context.

func (*Keymap) NewKeyBinding

func (k *Keymap) NewKeyBinding(binding key.Binding, essential bool)

NewKeyBinding registers a new key.Binding to the Keymap context. essential parameter allows to define if the key should appear on the short help or only in full help.

func (*Keymap) Reset

func (k *Keymap) Reset()

Reset is called when the manager switches contexts. Every Key are set back to visible and temporary CustomHelpDesc is cleared.

func (*Keymap) SetHelpDesc

func (k *Keymap) SetHelpDesc(keybind key.Binding, desc string)

SetHelpDesc allows for permanently change the default help text of the keybind. Only in the Keymap context

type KeymapContext

type KeymapContext string

KeymapContext is a special type used inside bubblehelp to serve as a unique identifier for different contexts.

type Style

type Style struct {
	EssentialKey               lipgloss.Style
	EssentialKeyDescription    lipgloss.Style
	EssentialKeySeparator      lipgloss.Style
	EssentialKeySeparatorValue string
	EssentialColSeparator      lipgloss.Style
	EssentialColSeparatorValue string
	FullKey                    lipgloss.Style
	FullKeyDescription         lipgloss.Style
	FullKeySeparator           lipgloss.Style
	FullKeySeparatorValue      string
	FullColSeparator           lipgloss.Style
	FullColSeparatorValue      string
}

Style describes every rendering aspect of bubblehelp.