palette

type Command struct {
	ID   string
	Name string
	Desc string
	// Run is invoked when the user selects this command and presses
	// Enter. It may return nil if there's nothing to dispatch.
	Run func() tea.Cmd
}

type DefaultDelegate struct {
	Styles          DelegateStyles
	ShowDescription bool
}

type DefaultItem interface {
	Item
	Title() string
	Description() string
}

type DelegateStyles struct {
	Title            lipgloss.Style
	Description      lipgloss.Style
	SelectedTitle    lipgloss.Style
	SelectedDesc     lipgloss.Style
	SelectionMarker  string
	UnselectedMarker string
}

type Facet struct {
	// Name is the prefix users type before ":" to trigger completion.
	// Should not contain whitespace or ":".
	Name string

	// Desc is an optional context hint shown above the value list
	// while completing this facet.
	Desc string

	// Items returns sync values for the given partial. The host owns
	// the filtering; the palette doesn't post-filter the returned
	// slice.
	Items func(partial string) []Item

	// Resolve dispatches an async value lookup. The returned tea.Cmd
	// must eventually emit a FacetResultMsg whose Facet and Partial
	// match the inputs. The ctx is canceled when the partial changes,
	// the cursor leaves the token, or the palette is Reset.
	Resolve func(ctx context.Context, partial string) tea.Cmd

	// Debounce delays Resolve dispatch after the partial last changed.
	// Ignored when Resolve is nil.
	Debounce time.Duration
}

type FacetResultMsg struct {
	Facet   string
	Partial string
	Results []Item
	Err     error
}

type Item interface {
	FilterValue() string
}

type ItemDelegate interface {
	// Height is the number of terminal rows one item occupies.
	Height() int
	// Spacing is the number of blank rows between adjacent items.
	Spacing() int
	// Update receives messages while the delegate is active. Implement
	// item-level keybindings here, or return nil to opt out.
	Update(msg tea.Msg, m *Model) tea.Cmd
	// Render draws one item at the given visible index to w.
	Render(w io.Writer, m Model, index int, item Item)
}

type KeyMap struct {
	Execute  key.Binding
	Cancel   key.Binding
	Down     key.Binding
	Up       key.Binding
	NextPage key.Binding
	PrevPage key.Binding

	// Navigate is a display-only binding rendered in ShortHelp() as a
	// combined arrow legend (default "↑↓ navigate"). It's never
	// matched in Update — Up/Down/Ctrl+P/Ctrl+N do the actual cursor
	// work. Override the help text (e.g. "↑↓ select") by reassigning
	// this field.
	Navigate key.Binding
}

type Mode struct {
	// Name identifies the mode for logging and host status displays.
	// Also used as the cache key for Search results — see
	// Model.Results.
	Name string

	// Prompt is the glyph rendered before the input field. Should be
	// the same display width as the configured spinner so the input
	// text doesn't shift when the spinner swaps in during search. An
	// empty Prompt falls back to defaultPrompt ("⣿ ").
	Prompt string

	// Placeholder is the hint text shown in the input while it's empty
	// and this mode is active. Empty falls back to the palette-level
	// placeholder set via WithPlaceholder.
	Placeholder string

	// EmptyMessage is shown in place of the item list when this mode
	// is active, the user has typed a query, and Items returns no
	// candidates. Empty falls back to the palette-level message set
	// via WithEmptyMessage; when both are empty no message is rendered.
	EmptyMessage string

	// Debounce is how long the palette waits after the input stops
	// changing before invoking Search. Zero means dispatch on the
	// next tick. Ignored when Search is nil.
	Debounce time.Duration

	// Match reports whether this mode applies to the given raw input.
	// A nil Match matches anything.
	Match func(input string) bool

	// Query extracts the meaningful query string from the raw input —
	// typically by stripping a leading prefix. A nil Query returns
	// the input unchanged.
	Query func(input string) string

	// Items returns the candidate items for this mode given the
	// palette state and the extracted query. For sync modes it does
	// the filtering inline; for async modes it typically reads from
	// the palette's Results cache that Search populates. A nil Items
	// returns nil.
	Items func(m Model, query string) []Item

	// Search is the async dispatcher. When the input changes inside
	// this mode and the debounce window elapses, the palette calls
	// Search and the returned tea.Cmd must eventually yield a
	// SearchResultMsg with the matching Mode name. The ctx is
	// canceled when a newer search supersedes this one or when the
	// active mode changes — implementations should pass it through
	// to their HTTP/DB call. Nil means the mode is purely synchronous.
	Search func(ctx context.Context, query string) tea.Cmd

	// Facets registers typeable "<Name>:<value>" filters for this
	// mode. When the cursor sits inside such a token, the palette
	// swaps the item list for a value picker scoped to the matching
	// Facet. See palette.ParseFacets to apply parsed filters from a
	// Mode's Items/Search closure.
	Facets []Facet
}

type Model struct {
	KeyMap KeyMap
	Styles Styles
	// contains filtered or unexported fields
}

type Option func(*Model)

type SearchResultMsg struct {
	Mode    string
	Query   string
	Results []Item
	Err     error
}

type SelectedMsg struct {
	Item Item
}

type Styles struct {
	// Container wraps the whole palette. The default is a rounded
	// border with no padding — padding is applied manually as a
	// per-line indent so selection backgrounds can fill the full row.
	Container lipgloss.Style
	// Title styles the optional section header at the top of the
	// palette (see WithTitle).
	Title lipgloss.Style
	// Indent is the per-line left margin inside the container, as a
	// literal string. Two spaces by default.
	Indent string
	// Prompt styles the leading mode-prompt glyph rendered in front of
	// the input. Not applied while the spinner is in flight (the
	// spinner owns its own styling).
	Prompt lipgloss.Style
	// Placeholder styles the textinput's placeholder text shown while
	// the input is empty. Propagated into the underlying textinput's
	// Focused / Blurred placeholder styles.
	Placeholder lipgloss.Style
	// EmptyMessage styles the no-results message rendered in place of
	// the item list when the active mode returns no candidates for the
	// current query. See Mode.EmptyMessage and WithEmptyMessage.
	EmptyMessage lipgloss.Style
	// SpinnerLabel styles the text next to the spinner glyph while a
	// search is in flight.
	SpinnerLabel lipgloss.Style
	// FacetHeader styles the facet-completion hint shown in the footer
	// row while the palette is completing a facet token.
	FacetHeader lipgloss.Style
	// Footer wraps the paginator row at the bottom.
	Footer lipgloss.Style
}