picker

Documentation

Overview

Package picker is a fuzzy-filtered selection overlay for nook. It is the underlying primitive behind file picker, buffer picker, symbol picker, and branch picker.

An Item carries a Title (rendered), an optional Subtitle, optional Group label, and an opaque Value. Consumers feed items in, route keys through Update, and observe SelectMsg / CancelMsg.

The default matcher is a subsequence-with-bonuses scorer (start-of-string, word-boundary, consecutive). Replace it with WithMatcher when needed.

Index

• func Score(target, query string) int
• func SubsequenceMatcher(it Item, query string) int
• type CancelMsg
• type Item
• type Matcher
• type Picker
  • func New(t theme.Theme) Picker
  • func (p Picker) AppendItems(items []Item) Picker
  • func (p Picker) Count() int
  • func (p Picker) Filter() string
  • func (p Picker) Highlighted() (Item, bool)
  • func (p Picker) SetTheme(t theme.Theme) Picker
  • func (p Picker) TotalCount() int
  • func (p Picker) Update(msg tea.Msg) (Picker, tea.Cmd)
  • func (p Picker) View() string
  • func (p Picker) WithFilter(s string) Picker
  • func (p Picker) WithItems(items []Item) Picker
  • func (p Picker) WithMatcher(m Matcher) Picker
  • func (p Picker) WithPlaceholder(s string) Picker
  • func (p Picker) WithPreview(f PreviewFunc) Picker
  • func (p Picker) WithSize(w, h int) Picker
  • func (p Picker) WithTitle(s string) Picker
• type PreviewFunc
• type SelectMsg

Functions

func Score

func Score(target, query string) int

Score evaluates the fuzzy match of query against target. Returns 0 if query is not a subsequence of target. Higher = better match.

func SubsequenceMatcher

func SubsequenceMatcher(it Item, query string) int

SubsequenceMatcher scores items by subsequence match with bonuses for start-of-string, word-boundary, and consecutive runs. Returns 0 if query chars don't all appear in order.

Types

type CancelMsg

type CancelMsg struct{}

CancelMsg is emitted when the user presses Esc.

type Item

type Item struct {
	Title    string // primary label
	Subtitle string // optional secondary label, dimmed
	Group    string // optional group label, used by matchers
	Value    any    // opaque payload returned in SelectMsg
}

Item is one row.

type Matcher

type Matcher func(it Item, query string) int

Matcher returns a score for it against query. Zero score drops the item; higher scores rank earlier.

type Picker

type Picker struct {
	// contains filtered or unexported fields
}

Picker is the model.

func New

func New(t theme.Theme) Picker

New constructs a picker with the default fuzzy matcher.

func (Picker) AppendItems

func (p Picker) AppendItems(items []Item) Picker

AppendItems streams new items into the picker, preserving the cursor.

func (Picker) Count

func (p Picker) Count() int

Count returns the number of items currently matching the filter.

func (Picker) Filter

func (p Picker) Filter() string

Filter returns the current filter string.

func (Picker) Highlighted

func (p Picker) Highlighted() (Item, bool)

Highlighted returns the currently highlighted item (if any).

func (Picker) SetTheme

func (p Picker) SetTheme(t theme.Theme) Picker

SetTheme swaps the palette used for the border, title, input, and highlighted match row. Next View() picks up the new colors.

func (Picker) TotalCount

func (p Picker) TotalCount() int

TotalCount returns the number of items in the picker, before filtering.

func (Picker) Update

func (p Picker) Update(msg tea.Msg) (Picker, tea.Cmd)

Update routes key events. It returns a tea.Cmd carrying SelectMsg or CancelMsg when those events occur.

func (Picker) View

func (p Picker) View() string

View renders the picker.

func (Picker) WithFilter

func (p Picker) WithFilter(s string) Picker

WithFilter presets the filter text.

func (Picker) WithItems

func (p Picker) WithItems(items []Item) Picker

WithItems replaces the item set.

func (Picker) WithMatcher

func (p Picker) WithMatcher(m Matcher) Picker

WithMatcher replaces the matching function.

func (Picker) WithPlaceholder

func (p Picker) WithPlaceholder(s string) Picker

WithPlaceholder sets the input placeholder.

func (Picker) WithPreview

func (p Picker) WithPreview(f PreviewFunc) Picker

WithPreview wires a preview renderer. If set and the picker is wide enough, the right half shows preview content for the highlighted item.

func (Picker) WithSize

func (p Picker) WithSize(w, h int) Picker

WithSize sets the rendered width and height.

func (Picker) WithTitle

func (p Picker) WithTitle(s string) Picker

WithTitle sets the title rendered above the input.

type PreviewFunc

type PreviewFunc func(it Item) string

PreviewFunc renders preview content for the highlighted item. Return "" to skip the preview pane for that item.

type SelectMsg

type SelectMsg struct {
	Item Item
}

SelectMsg is emitted when the user presses Enter on a non-empty result list.