filter

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 New(opts Options) 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) Reset()
  • func (m *Model) SetBottomLeft(s string)
  • func (m *Model) SetBottomRight(s string)
  • func (m *Model) SetValue(s string)
  • func (m *Model) SetWidth(w int)
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) Value() string
  • func (m Model) View() string
• type Options

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

func New(opts Options) Model

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

func (m *Model) Focus() tea.Cmd

Focus grabs focus and returns the cursor-blink command. Always propagate the cmd — without it the cursor won't blink.

func (Model) Focused

func (m Model) Focused() bool

Focused reports whether the filter is currently accepting keystrokes.

func (Model) Help

func (m Model) Help() []key.Binding

Help returns the keys the filter responds to. Empty when blurred (the parent owns the "/" focus binding); commit/clear when focused.

func (*Model) Reset

func (m *Model) Reset()

Reset clears the value and blurs.

func (*Model) SetBottomLeft

func (m *Model) SetBottomLeft(s string)

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 (m *Model) SetBottomRight(s string)

func (*Model) SetValue

func (m *Model) SetValue(s string)

SetValue overwrites the current filter text. Useful when rebuilding the filter on theme swap / resize — carry the old Value() across.

func (*Model) SetWidth

func (m *Model) SetWidth(w int)

SetWidth resizes the surrounding pane. Height is fixed at 3.

func (Model) Update

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

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.

func (Model) Value

func (m Model) Value() string

Value is the current filter text. Read after every Update to drive the downstream list/table filter.

func (Model) View

func (m Model) View() string

View renders the filter as a bordered three-line pane.

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
	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.