action

type Action struct {
	// Label names the verb and titles its log event. Required.
	Label string

	// Desc is an optional gloss rendered beside the label.
	Desc string

	// Key is an optional shortcut. The menu dispatches it while open and
	// renders it in a right-hand column; it is deliberately not advertised
	// in the screen's Help(), since moving discovery off the footer and into
	// the menu is most of the point.
	Key key.Binding

	// Confirm, when non-empty, puts a yes/no modal between the pick and the
	// run. Use it for anything destructive rather than hand-rolling the
	// sequence.
	Confirm string

	// Disabled, when non-empty, renders the row dimmed and unselectable with
	// this text as the reason.
	//
	// Showing an unavailable verb beats hiding it: hidden, the user learns
	// the verb does not exist and goes looking in the docs; shown with a
	// reason, they learn it does not apply yet. The menu also fills this in
	// on its own — for a non-Multi action under a multi-selection, and for
	// an Exclusive action already in flight.
	Disabled string

	// Multi reports whether this action accepts a selection of more than
	// one. The zero value is false: an action acts on exactly one target
	// unless it says otherwise.
	//
	// The default runs the safe way round. "View logs" pushes one screen, so
	// forgetting to think about arity leaves a disabled row with an
	// explanation — noticed in the first five seconds of using the screen.
	// Were the default reversed, forgetting would ship a verb that picks one
	// of three marked targets arbitrarily, which is found in production.
	Multi bool

	// Exclusive refuses a second concurrent run for the same target. The
	// menu renders it disabled with a reason rather than dropping the press,
	// so the refusal is visible.
	Exclusive bool

	// ID scopes the Exclusive check. Defaults to Label; set it when two
	// screens share a label but not an identity.
	ID string

	// Run is background work. Prefer it: it can be attributed, grouped,
	// cancelled and reported on, none of which Do can be.
	Run Func

	// Do is the escape hatch for verbs that are not background work.
	//
	// Navigational Do actions are one-at-a-time by construction rather than
	// by declaration — pushing a screen replaces what is on top, so there is
	// no second one to push. It is a Do that does not navigate, one that
	// fires a request and returns, that may still want Exclusive.
	Do func() tea.Cmd
}

type CancelledMsg struct{}

type ChosenMsg struct {
	Action Action
	Target string
}

type Func func(ctx context.Context, out io.Writer) error

type Keys struct {
	Up, Down         key.Binding
	Top, Bottom      key.Binding
	HalfUp, HalfDown key.Binding
	Choose           key.Binding
	Cancel           key.Binding
}

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

type Options struct {
	// Title labels the menu. Defaults to "Actions"; the Set's Target is
	// appended when it has one, so a menu over a multi-selection announces
	// its blast radius on its own border.
	Title string

	// Set is the actions to offer.
	Set Set

	LabelStyle    lipgloss.Style
	DescStyle     lipgloss.Style
	KeyStyle      lipgloss.Style
	SelectedStyle lipgloss.Style
	DisabledStyle lipgloss.Style

	ActiveColor    lipgloss.TerminalColor
	InactiveColor  lipgloss.TerminalColor
	ActiveBorder   lipgloss.Border
	InactiveBorder lipgloss.Border
	SlotBrackets   pane.SlotBracketStyle

	// MultiReason and RunningReason override the stock text the menu fills
	// into Disabled for a non-Multi action under a multi-selection, and for
	// an Exclusive action already in flight.
	MultiReason   string
	RunningReason string

	Keys Keys
}

type Provider interface {
	Actions() Set
}

type RetargetMsg struct {
	// Event is the press, forwarded untouched so the host can route it to
	// whatever is underneath before it reopens.
	Event mouse.Msg
}

type Set struct {
	// Target names the object of the verbs for display — "cache-redis",
	// "3 items". It titles the menu.
	//
	// It is the whole reason Set is a struct rather than a bare slice: once
	// rows can be marked, "Delete" means one row or twelve, and the menu is
	// the last surface that can say which before it happens.
	Target string

	// Count is how many targets Actions will act on. 0 and 1 both mean a
	// single target; above that, actions without Multi are disabled.
	Count int

	Actions []Action
}