Documentation
¶
Overview ¶
Package help renders key-binding hints in three shapes:
- ShortView / ShortViewBudget — a single inline line, "key desc • key desc • …", sized to fit a width budget. The app shell paints this into the statusbar's left slot. When the bindings don't all fit and m.Expanded() is false, ShortViewBudget tight-packs bindings and appends a "? help" affordance. When m.Expanded() is true, the line becomes row 0 of a column-aligned grid whose last cell is the "? close" affordance; rows 1+ continue in ExpandedView with the same column widths, so labels line up vertically across the footer and the panel.
- ExpandedView / ExpandedRows — the rows-1-and-onward continuation of the unified grid: same column widths as the footer's row 0, same " • " column separator, row count clamped to maxRows. The app shell renders this in a Fixed row above the statusbar when m.Expanded() is true.
- View — a legacy bordered overlay (kept for parents that want a standalone popup); uses key/desc column-pair flowing.
The footer + panel together act as one component: when expanded, the footer is row 0 of the grid and the panel is rows 1+, so a single planGridFull pass at the statusbar's left-slot width drives both. Pressing the app's HelpKey ("?" by default) flips m.Expanded(); the shell only listens to the key when the inline flow has overflow, so when everything fits the affordance is hidden and the key is inert.
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 (m Model) Count() int
- func (m Model) Expanded() bool
- func (m Model) ExpandedRows(width, maxRows int) int
- func (m Model) ExpandedView(width, rows int) string
- func (m Model) Height() int
- func (m Model) Init() tea.Cmd
- func (m Model) Minimal() bool
- func (m Model) PadLines(s string, leftPad, rightPad int) string
- func (m *Model) SetBindings(b []key.Binding)
- func (m *Model) SetDimensions(w, h int)
- func (m *Model) SetExpanded(b bool)
- func (m *Model) SetMinimal(b bool)
- func (m Model) ShortView() string
- func (m Model) ShortViewBudget(width int) (line string, consumed int, overflow bool)
- func (m *Model) ToggleExpanded() bool
- func (m Model) Update(_ tea.Msg) (Model, tea.Cmd)
- func (m Model) View() string
- func (m Model) Width() int
- type Options
- type Provider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
Model renders the help strip + expanded panel + bordered overlay. Call SetBindings whenever the active binding set changes; the three render methods (ShortView/ShortViewBudget, ExpandedView, View) all read from the same compiled list. Visibility of the bordered View is the parent's concern; the footer + panel are wired by pkg/app and follow the Expanded() state plus overflow detection from ShortViewBudget.
func (Model) Expanded ¶
Expanded reports whether the multi-row panel view should be rendered (the app shell consults this when deciding whether to reserve rows for ExpandedView above the statusbar).
func (Model) ExpandedRows ¶
ExpandedRows reports how many panel rows ExpandedView needs at width, clamped to maxRows. The unified grid puts the footer at row 0 and the panel at rows 1+; this returns the number of rows 1+ that hold the remaining bindings. Width or maxRows ≤ 0, model not expanded, or all bindings fit in row 0 yields 0.
func (Model) ExpandedView ¶
ExpandedView renders rows 1+ of the unified grid at width. Column widths come from the same planGridFull pass that ShortViewBudget uses for row 0, so labels line up vertically across the footer and panel. Each row is padded to width with DescStyle so any background color set on DescStyle fills the row edge to edge. Stops when it has filled rows lines or run out of bindings, whichever comes first. Returns empty when not expanded or when all bindings fit on row 0.
func (Model) PadLines ¶
PadLines wraps each line of s with leftPad and rightPad DescStyle- rendered spaces so a background color from DescStyle extends across the padded edges. Use it in the app shell to align the panel with the statusbar's left-slot padding (so panel columns sit at the same visible x as the footer's row 0) and to fill the row's right edge to full terminal width.
func (*Model) SetBindings ¶
func (*Model) SetDimensions ¶
func (*Model) SetExpanded ¶
SetExpanded controls whether the model is in the expanded state. Use ToggleExpanded for the keyboard-driven flip.
func (*Model) SetMinimal ¶
SetMinimal flips minimal-footer mode at runtime. See Options.Minimal.
func (Model) ShortView ¶
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) ShortViewBudget ¶
ShortViewBudget renders the footer line fitting within width visible cells. Behavior depends on m.Expanded():
- When collapsed (m.Expanded() == false), bindings are tight-packed inline ("key desc • key desc • …") until the next one would not fit; a "? help" affordance is appended on overflow.
- When expanded (m.Expanded() == true), the line becomes row 0 of a column-aligned grid whose last cell is the "? close" affordance. ExpandedView renders rows 1+ of the same grid at the same width so footer and panel columns align vertically.
consumed reports how many bindings were placed on the line. overflow reports whether bindings were dropped because they didn't fit (in expanded mode, true when the grid spills into rows 1+). Width 0 or less skips budgeting and falls back to ShortView.
func (*Model) ToggleExpanded ¶
ToggleExpanded flips the expanded state and reports the new value.
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
// Minimal collapses the footer to just the "? help" / "? close"
// affordance regardless of how many bindings the model holds — the
// inline strip is hidden and pressing the help key is the only way
// to see hints. When expanded, every binding flows into the panel
// rows. Set via SetMinimal at runtime.
Minimal bool
}
Options configures a help overlay. Zero-value fields fall back to defaults.
Source Files