overlay

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 12, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package overlay owns all layered popup UI for revdiff — help, annotation list, and theme selector overlays. It provides a Manager coordinator that enforces mutual exclusivity (only one overlay visible at a time), routes key dispatch to the active overlay, and composes the overlay on top of the base view via ANSI-aware centered compositing.

Callers supply fully populated spec structs (HelpSpec, AnnotListSpec, ThemeSelectSpec) when opening an overlay and handle side effects by switching on the returned Outcome from HandleKey. The overlay package has no dependency on ui.Model, annotation store, theme loading, or any filesystem operation.

Index

Constants

View Source 
const WheelStep = 3

WheelStep is the offset delta applied per plain wheel notch inside overlay popups. exported so app/ui can reuse the same constant for diff-pane wheel scrolling — keeps the feel consistent across overlay and non-overlay panes.

Variables

This section is empty.

Functions

This section is empty.

Types

type AnnotListSpec 

type AnnotListSpec struct {
	Items []AnnotationItem
}

AnnotListSpec describes the annotation list popup content.

type AnnotationItem 

type AnnotationItem struct {
	AnnotationTarget
	Comment string
}

AnnotationItem is one entry in the annotation list popup. embeds AnnotationTarget for the jump destination; Comment is the display text.

type AnnotationTarget 

type AnnotationTarget struct {
	File       string
	ChangeType string
	Line       int
}

AnnotationTarget identifies the jump destination for an annotation list selection.

type HelpEntry 

type HelpEntry struct {
	Keys        string
	Description string
}

HelpEntry is a single key-description pair in a help section.

type HelpSection 

type HelpSection struct {
	Title   string
	Entries []HelpEntry
}

HelpSection is a titled group of key bindings inside the help overlay.

type HelpSpec 

type HelpSpec struct {
	Sections []HelpSection
}

HelpSpec describes the help overlay content.

type InfoRow added in v0.27.0 

type InfoRow struct {
	Label       string
	Value       string
	MutedSuffix string
}

InfoRow is a label/value line rendered in the session section of the info popup. MutedSuffix is an optional secondary text rendered after Value in the muted foreground color, used for "name (path)"-style rows where the primary token (project name, file basename) deserves prominence and the secondary token (full path) is contextual. Empty MutedSuffix renders as a plain Value row.

type InfoSpec added in v0.27.0 

type InfoSpec struct {
	// HeaderText is rendered as the centered top-border label. Typically a
	// compact mode summary ("vs HEAD~3", "stdin patch.diff", "working tree").
	// Empty falls back to the literal " info " title.
	HeaderText string
	// FooterText is rendered as a centered bottom-border label, used to
	// surface aggregate stats (files, +/-, status, vcs) without spending
	// body rows on them. Empty leaves the bottom border bare. Both
	// header and footer gracefully no-op when too wide for the popup.
	FooterText        string
	Description       string
	Rows              []InfoRow
	Commits           []diff.CommitInfo
	CommitsApplicable bool
	CommitsLoaded     bool
	Truncated         bool
	CommitsErr        error
}

InfoSpec describes the unified info popup, composed of three optional sections rendered top-to-bottom: an agent-supplied prose description (#130 — empty hides the section), invocation/session info from --description-less review-info plumbing (Rows; always shown when non-empty), and the commit log for the current ref range (Commits; gated by CommitsApplicable so modes without a meaningful range — stdin/staged/all-files/file-only — hide the commits section entirely instead of rendering "no commits in this mode").

CommitsApplicable=false hides the commits section so the popup is never a dead-end: the session section explains the mode, and there's no need to duplicate that as a "no commits" message.

Truncated marks the commit list as capped at diff.MaxCommits entries. CommitsErr surfaces a CommitLog fetch error inside the commits section, taking precedence over the empty-list message; it does not gate the popup.

type Kind 

type Kind int

Kind identifies which overlay is currently active. 

const (
	KindNone        Kind = iota
	KindHelp             // help overlay
	KindAnnotList        // annotation list popup
	KindThemeSelect      // theme selector popup
	KindInfo             // unified info popup (description + session + commits)
)

type Manager 

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

Manager coordinates overlay lifecycle: open/close, key routing, and render composition. Only one overlay can be active at a time.

func NewManager 

func NewManager() *Manager

NewManager creates a Manager with no active overlay.

func (*Manager) Active 

func (m *Manager) Active() bool

Active reports whether any overlay is currently visible.

func (*Manager) Close 

func (m *Manager) Close()

Close dismisses whatever overlay is active.

func (*Manager) Compose 

func (m *Manager) Compose(base string, ctx RenderCtx) string

Compose renders the active overlay on top of base using centered compositing. returns base unchanged when no overlay is active.

func (*Manager) HandleKey 

func (m *Manager) HandleKey(msg tea.KeyMsg, action keymap.Action) Outcome

HandleKey routes a key press to the active overlay and returns the outcome. auto-closes the overlay for outcomes that imply dismissal. returns Outcome{Kind: OutcomeNone} when no overlay is active.

func (*Manager) HandleMouse added in v0.24.0 

func (m *Manager) HandleMouse(msg tea.MouseMsg) Outcome

HandleMouse routes a mouse event to the active overlay. wheel events drive per-overlay scroll/cursor navigation; left-clicks inside the popup hit-test an item row and can produce selection outcomes (jump/confirm); clicks outside the popup and other buttons are consumed without side effects. returns Outcome{Kind: OutcomeNone} when no overlay is active. mirrors HandleKey: outcomes that imply dismissal auto-close.

left-click coords are translated to popup-local coords before dispatch so each overlay can reason about its own layout (border + padding + content rows) without knowing screen geometry. clicks outside the popup bounds are swallowed rather than dismissing the overlay — intentionally conservative to avoid accidental closes.

func (*Manager) Kind 

func (m *Manager) Kind() Kind

Kind returns the currently active overlay kind.

func (*Manager) OpenAnnotList 

func (m *Manager) OpenAnnotList(spec AnnotListSpec)

OpenAnnotList activates the annotation list popup with the given spec.

func (*Manager) OpenHelp 

func (m *Manager) OpenHelp(spec HelpSpec)

OpenHelp activates the help overlay with the given spec.

func (*Manager) OpenInfo added in v0.27.0 

func (m *Manager) OpenInfo(spec InfoSpec)

OpenInfo activates the unified info popup with the given spec.

func (*Manager) OpenThemeSelect 

func (m *Manager) OpenThemeSelect(spec ThemeSelectSpec)

OpenThemeSelect activates the theme selector popup with the given spec.

func (*Manager) UpdateInfo added in v0.27.0 

func (m *Manager) UpdateInfo(spec InfoSpec)

UpdateInfo replaces the active info popup's spec without resetting the user's scroll position. Used when async data (review-stats fetch, commit-log fetch) lands while the popup is open — the popup re-reads the new spec on the next render and the user sees the loading state flip to loaded inline. No-op when the active overlay is not the info popup, so callers can fire it unconditionally without checking Kind() first.

type Outcome 

type Outcome struct {
	Kind             OutcomeKind
	AnnotationTarget *AnnotationTarget
	ThemeChoice      *ThemeChoice
}

Outcome is the return value from HandleKey. Callers switch on Kind and read AnnotationTarget or ThemeChoice for the relevant outcome.

type OutcomeKind 

type OutcomeKind int

OutcomeKind describes what happened after a key press in an overlay. 

const (
	OutcomeNone             OutcomeKind = iota // key consumed, no side effect
	OutcomeClosed                              // overlay was closed
	OutcomeAnnotationChosen                    // user picked an annotation (target in Outcome.AnnotationTarget)
	OutcomeThemePreview                        // cursor moved to a new theme (name in Outcome.ThemeChoice)
	OutcomeThemeConfirmed                      // user confirmed a theme (name in Outcome.ThemeChoice)
	OutcomeThemeCanceled                       // user canceled theme selection
)

type RenderCtx 

type RenderCtx struct {
	Width    int
	Height   int
	Resolver Resolver
}

RenderCtx carries per-render parameters passed to Compose.

type Resolver 

type Resolver interface {
	Style(k style.StyleKey) lipgloss.Style
	Color(k style.ColorKey) style.Color
}

Resolver is a narrow view of style.Resolver consumed by overlay rendering.

type ThemeChoice 

type ThemeChoice struct {
	Name string
}

ThemeChoice carries the selected theme name.

type ThemeItem 

type ThemeItem struct {
	Name        string
	Local       bool
	AccentColor string
}

ThemeItem is one entry in the theme selector list.

type ThemeSelectSpec 

type ThemeSelectSpec struct {
	Items      []ThemeItem
	ActiveName string
}

ThemeSelectSpec describes the theme selector popup content.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.