Add simple helper package for making user-definable keymappings and help bubble

README.md

@@ -80,6 +80,52 @@ indenting and text wrapping.
 [reflow]: https://github.com/muesli/reflow
 
 
+## Help
+
+A customizable horizontal mini help view that automatically generates itself
+from your keybindings. It features single and multi-line modes, which the user
+can optionally toggle between. It will truncate gracefully if the terminal is
+too wide for the content.
+
+
+## Key
+
+A non-visual component for managing keybindings. It’s useful for allowing users
+to remap keybindings as well as generating help views corresponding to your
+keybindings.
+
+```go
+type KeyMap struct {
+    Up key.Binding
+    Down key.Binding
+}
+
+var DefaultKeyMap = KeyMap{
+    Up: key.NewBinding(
+        key.WithKeys("k", "up"),
+        key.WithHelp("↑/k", "move up"),
+    ),
+    Down: key.Binding{
+        WithKeys("j", "down"),
+        WithHelp("↓/j", "move down"),
+    },
+}
+
+func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+    switch msg := msg.(type) {
+    case tea.KeyMsg:
+        switch {
+        case key.Matches(msg, DefaultKeyMap.Up):
+            // The user pressed up
+        case key.Matches(msg, DefaultKeyMap.Down):
+            // The user pressed down
+        }
+    }
+    return m, nil
+}
+```
+
+
 ## Additional Bubbles
 
 * [promptkit](https://github.com/erikgeiser/promptkit): A collection of common

help/help.go

@@ -0,0 +1,224 @@
+package help
+
+import (
+	"strings"
+
+	"github.com/charmbracelet/bubbles/key"
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+)
+
+// KeyMap is a map of keybindings used to generate help. Since it's an
+// interface it can be any type, though struct or a map[string][]key.Binding
+// are likely candidates.
+//
+// Note that if a key is disabled (via key.Binding.SetEnabled) it will not be
+// rendered in the help view, so in theory generated help should self-manage.
+type KeyMap interface {
+
+	// ShortHelp returns a slice of bindings to be displayed in the short
+	// version of the help. The help bubble will render help in the order in
+	// which the help items are returned here.
+	ShortHelp() []key.Binding
+
+	// MoreHelp returns an extended group of help items, grouped by columns.
+	// The help bubble will render the help in the order in which the help
+	// items are returned here.
+	FullHelp() [][]key.Binding
+}
+
+// Styles is a set of available style definitions for the Help bubble.
+type Styles struct {
+	Ellipsis lipgloss.Style
+
+	// Styling for the short help
+	ShortKey       lipgloss.Style
+	ShortDesc      lipgloss.Style
+	ShortSeparator lipgloss.Style
+
+	// Styling for the full help
+	FullKey       lipgloss.Style
+	FullDesc      lipgloss.Style
+	FullSeparator lipgloss.Style
+}
+
+// Model contains the state of the help view.
+type Model struct {
+	Width   int
+	ShowAll bool // if true, render the "full" help menu
+
+	ShortSeparator string
+	FullSeparator  string
+
+	// The symbol we use in the short help when help items have been truncated
+	// due to width. Periods of ellipsis by default.
+	Ellipsis string
+
+	Styles Styles
+}
+
+// NewModel creates a new help view with some useful defaults.
+func NewModel() Model {
+	keyStyle := lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{
+		Light: "#909090",
+		Dark:  "#626262",
+	})
+
+	descStyle := lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{
+		Light: "#B2B2B2",
+		Dark:  "#4A4A4A",
+	})
+
+	sepStyle := lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{
+		Light: "#DDDADA",
+		Dark:  "#3C3C3C",
+	})
+
+	return Model{
+		ShortSeparator: " • ",
+		FullSeparator:  "    ",
+		Ellipsis:       "…",
+		Styles: Styles{
+			ShortKey:       keyStyle,
+			ShortDesc:      descStyle,
+			ShortSeparator: sepStyle,
+			Ellipsis:       sepStyle.Copy(),
+			FullKey:        keyStyle.Copy(),
+			FullDesc:       descStyle.Copy(),
+			FullSeparator:  sepStyle.Copy(),
+		},
+	}
+}
+
+// Update helps satisfy the Bubble Tea Model interface. It's a no-op.
+func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
+	return m, nil
+}
+
+// View renders the help view's current state.
+func (m Model) View(k KeyMap) string {
+	if m.ShowAll {
+		return m.FullHelpView(k.FullHelp())
+	}
+	return m.ShortHelpView(k.ShortHelp())
+}
+
+// ShortHelpView renders a single line help view from a slice of keybindings.
+// If the line is longer than the maximum width it will be gracefully
+// truncated, showing only as many help items as possible.
+func (m Model) ShortHelpView(bindings []key.Binding) string {
+	if len(bindings) == 0 {
+		return ""
+	}
+
+	var b strings.Builder
+	var totalWidth int
+	var separator = m.Styles.ShortSeparator.Inline(true).Render(m.ShortSeparator)
+
+	for i, kb := range bindings {
+		if !kb.Enabled() {
+			continue
+		}
+
+		var sep string
+		if totalWidth > 0 && i < len(bindings) {
+			sep = separator
+		}
+
+		str := sep +
+			m.Styles.ShortKey.Inline(true).Render(kb.Help().Key) + " " +
+			m.Styles.ShortDesc.Inline(true).Render(kb.Help().Desc)
+
+		w := lipgloss.Width(str)
+
+		// If adding this help item would go over the available width, stop
+		// drawing.
+		if m.Width > 0 && totalWidth+w > m.Width {
+			// Although if there's room for an ellipsis, print that.
+			tail := " " + m.Styles.Ellipsis.Inline(true).Render(m.Ellipsis)
+			tailWidth := lipgloss.Width(tail)
+
+			if totalWidth+tailWidth < m.Width {
+				b.WriteString(tail)
+			}
+
+			break
+		}
+
+		totalWidth += w
+		b.WriteString(str)
+	}
+
+	return b.String()
+}
+
+// FullHelpView renders help columns from a slice of key binding slices. Each
+// top level slice entry renders into a column.
+func (m Model) FullHelpView(groups [][]key.Binding) string {
+	if len(groups) == 0 {
+		return ""
+	}
+
+	var (
+		out        []string
+		totalWidth int
+		sep        = m.Styles.FullSeparator.Render(m.FullSeparator)
+		sepWidth   = lipgloss.Width(sep)
+	)
+
+	// Iterate over groups to build columns
+	for i, group := range groups {
+		if group == nil || !shouldRenderColumn(group) {
+			continue
+		}
+
+		var (
+			keys         []string
+			descriptions []string
+		)
+
+		// Separate keys and descriptions into different slices
+		for _, kb := range group {
+			if !kb.Enabled() {
+				continue
+			}
+			keys = append(keys, kb.Help().Key)
+			descriptions = append(descriptions, kb.Help().Desc)
+		}
+
+		col := lipgloss.JoinHorizontal(lipgloss.Top,
+			m.Styles.FullKey.Render(strings.Join(keys, "\n")),
+			m.Styles.FullKey.Render(" "),
+			m.Styles.FullDesc.Render(strings.Join(descriptions, "\n")),
+		)
+
+		// Column
+		totalWidth += lipgloss.Width(col)
+		if totalWidth > m.Width {
+			break
+		}
+
+		out = append(out, col)
+
+		// Separator
+		if i < len(group)-1 {
+			totalWidth += sepWidth
+			if totalWidth > m.Width {
+				break
+			}
+		}
+
+		out = append(out, sep)
+	}
+
+	return lipgloss.JoinHorizontal(lipgloss.Top, out...)
+}
+
+func shouldRenderColumn(b []key.Binding) (ok bool) {
+	for _, v := range b {
+		if v.Enabled() {
+			return true
+		}
+	}
+	return false
+}

key/key.go

@@ -0,0 +1,139 @@
+// Package key provides some types and functions for generating user-definable
+// keymappings useful in Bubble Tea components. There are a few different ways
+// you can define a keymapping with this package. Here's one example:
+//
+//     type KeyMap struct {
+//         Up key.Binding
+//         Down key.Binding
+//     }
+//
+//     var DefaultKeyMap = KeyMap{
+//         Up: key.NewBinding(
+//             key.WithKeys("k", "up"),
+//             key.WithHelp("↑/k", "move up"),
+//         ),
+//         Down: key.Binding{
+//             WithKeys("j", "down"),
+//             WithHelp("↓/j", "move down"),
+//         },
+//     }
+//
+//     func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+//         switch msg := msg.(type) {
+//         case tea.KeyMsg:
+//             switch {
+//             case key.Matches(msg, DefaultKeyMap.Up):
+//                 // The user pressed up
+//             case key.Matches(msg, DefaultKeyMap.Down):
+//                 // The user pressed down
+//             }
+//         }
+//
+//         // ...
+//     }
+//
+// The help information, which is not used in the example above, can be used
+// to render help text for keystrokes in your views.
+package key
+
+import (
+	tea "github.com/charmbracelet/bubbletea"
+)
+
+// Binding describes a set of keybindings and, optionally, their associated
+// help text.
+type Binding struct {
+	keys     []string
+	help     Help
+	disabled bool
+}
+
+// BindingOpt is an initialization option for a keybinding. It's used as an
+// argument to NewBinding.
+type BindingOpt func(*Binding)
+
+// NewBinding returns a new keybinding from a set of BindingOpt options.
+func NewBinding(opts ...BindingOpt) Binding {
+	b := &Binding{}
+	for _, opt := range opts {
+		opt(b)
+	}
+	return *b
+}
+
+// WithKeys initializes a keybinding with the given keystrokes.
+func WithKeys(keys ...string) BindingOpt {
+	return func(b *Binding) {
+		b.keys = keys
+	}
+}
+
+// WithHelp initializes a keybinding with the given help text.
+func WithHelp(key, desc string) BindingOpt {
+	return func(b *Binding) {
+		b.help = Help{Key: key, Desc: desc}
+	}
+}
+
+// WithDisabled initializes a disabled keybinding.
+func WithDisabled() BindingOpt {
+	return func(b *Binding) {
+		b.disabled = true
+	}
+}
+
+// SetKeys sets the keys for the keybinding.
+func (b *Binding) SetKeys(keys ...string) {
+	b.keys = keys
+}
+
+// Keys returns the keys for the keybinding.
+func (b Binding) Keys() []string {
+	return b.keys
+}
+
+// SetHelp sets the help text for the keybinding.
+func (b *Binding) SetHelp(key, desc string) {
+	b.help = Help{Key: key, Desc: desc}
+}
+
+// Help returns the Help information for the keybinding.
+func (b Binding) Help() Help {
+	return b.help
+}
+
+// Enabled returns whether or not the keybinding is enabled. Disabled
+// keybindings won't be activated and won't show up in help. Keybindings are
+// enabled by default.
+func (b Binding) Enabled() bool {
+	return !b.disabled
+}
+
+// SetEnabled enables or disables the keybinding.
+func (b *Binding) SetEnabled(v bool) {
+	b.disabled = !v
+}
+
+// Unbind removes the keys and help from this binding, effectively nullifying
+// it. This is a step beyond disabling it, since applications can enable
+// or disable key bindings based on application state.
+func (b *Binding) Unbind() {
+	b.keys = nil
+	b.help = Help{}
+}
+
+// Help is help information for a given keybinding.
+type Help struct {
+	Key  string
+	Desc string
+}
+
+// Matches checks if the given KeyMsg matches a given binding.
+func Matches(k tea.KeyMsg, b Binding) bool {
+	for _, v := range b.keys {
+		if k.String() == v && b.Enabled() {
+			return true
+		}
+	}
+	return false
+}