Documentation
¶
Overview ¶
Package filter provides a single-line textinput wrapped in a pane — the "press / to search, enter to commit, esc to clear" pattern every TUI eventually needs. Model owns its focus state and the commit/cancel key handling; the caller reads Value() after each Update to drive whatever list or table is being filtered. SetBottomLeft / SetBottomRight expose the surrounding pane's bottom-border slots so a host (e.g. pkg/table) can paint hints, completion previews, or counts into the filter chrome without wrapping it in a second pane.
Index ¶
- type Model
- func (m *Model) Blur()
- func (m *Model) Focus() tea.Cmd
- func (m Model) Focused() bool
- func (m Model) Help() []key.Binding
- func (m Model) Inline() bool
- func (m Model) InlineView() string
- func (m Model) IsCapturingKeys() bool
- func (m Model) Rect() geom.Rect
- func (m *Model) Reset()
- func (m *Model) SetBottomLeft(s string)
- func (m *Model) SetBottomRight(s string)
- func (m *Model) SetInlineRect(r geom.Rect)
- func (m *Model) SetRect(r geom.Rect)
- func (m *Model) SetValue(s string)
- func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
- func (m Model) Value() string
- func (m Model) View() string
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
Model is the filter's exported state. Focus state lives on both the embedded textinput (so keys route correctly) and the pane (so the border color reflects focus) — toggle them together via Focus/Blur.
func New ¶
New constructs a filter. Call Update/View from the parent model; use Focus/Blur/Value/Reset to drive it.
func (*Model) Blur ¶
func (m *Model) Blur()
Blur releases focus without touching the value. See Reset for clearing.
func (*Model) Focus ¶
Focus grabs focus and returns the cursor-blink command. Always propagate the cmd — without it the cursor won't blink.
func (Model) Help ¶
Help returns the keys the filter responds to. Empty when blurred (the parent owns the "/" focus binding); commit/clear when focused. Help returns the bindings active while the filter has focus.
pkg/help owns the overlay that renders these, and pkg/help embeds a filter.Model of its own for its search field — so this package cannot import it back to group them. The bindings are always surfaced by the component the filter belongs to (list, table, tree, …), which puts them under its own Filter or Search group; there is no path by which a bare filter's keys reach the overlay ungrouped.
func (Model) Inline ¶ added in v0.18.1
Inline reports whether the filter is rendering as a row inside a host's pane rather than as its own pane.
func (Model) InlineView ¶ added in v0.18.1
InlineView renders just the input line — no border, no pane. Used by components that host the filter inside their own pane so the filter reads as part of the thing it filters instead of a sibling box floating above it.
func (Model) IsCapturingKeys ¶ added in v0.18.0
IsCapturingKeys reports whether the filter owns the keyboard — true whenever it is focused. Satisfies focus.Capturer.
func (Model) Rect ¶ added in v0.18.0
Rect returns the rect the filter was last placed at — its own pane's rect normally, or the host-assigned row when inline.
func (*Model) SetBottomLeft ¶
SetBottomLeft / SetBottomRight write into the surrounding pane's bottom border slots. Useful for hints, completion previews, or counts that pertain to whatever the filter is driving. Pass "" to clear.
func (*Model) SetBottomRight ¶
func (*Model) SetInlineRect ¶ added in v0.18.1
SetInlineRect places the filter as a single row inside a host component's pane, rather than as a pane of its own. The host renders InlineView into its pane header; this call is what makes the filter's own hit-testing agree with where the host actually drew it.
func (*Model) SetRect ¶ added in v0.18.0
SetRect places the filter at r. Height is fixed at 3 regardless of what the rect offers, since the pane is border + one content row + border.
func (*Model) SetValue ¶
SetValue overwrites the current filter text. Useful when rebuilding the filter on theme swap / resize — carry the old Value() across.
func (Model) Update ¶
Update is a no-op when blurred. When focused, "enter" commits (blur, keep value) and "esc" cancels (reset + blur); anything else is forwarded to the textinput. The caller should still forward every message — the filter decides whether to act on it.
type Options ¶
type Options struct {
Width int
// Title sits on the top border of the pane. Defaults to "filter".
Title string
// Prompt appears before the cursor inside the input. Defaults to "/ ".
Prompt string
// Placeholder shows when the input is empty.
Placeholder string
// CharLimit caps input length. Defaults to 64.
CharLimit int
// Text-input styling.
PromptStyle lipgloss.Style
TextStyle lipgloss.Style
PlaceholderStyle lipgloss.Style
CursorColor lipgloss.TerminalColor
// Pane pass-throughs. Unset fields fall back to filter's defaults, which
// differ from the base pane's (NormalBorder both states, no slot brackets)
// because a filter bar reads cleaner without thick borders or corner tabs.
ActiveColor lipgloss.TerminalColor
InactiveColor lipgloss.TerminalColor
ActiveBorder lipgloss.Border
InactiveBorder lipgloss.Border
// Glyphs are the marks this component draws, plus the scrollbar
// thumb and track it hands to its pane. Empty fields fall back to
// glyph.Default.
Glyphs glyph.Set
SlotBrackets pane.SlotBracketStyle
}
Options configures a new filter. Zero-value fields fall back to sensible defaults so a caller can `filter.New(filter.Options{Width: w})` and get a working, un-themed filter bar.
Source Files