logview

Documentation

Overview

Package logview is a streaming text viewer with incremental search and keyboard navigation, wrapped in a pane.

Use it for tailing logs, command output, or any append-mostly text where the user wants to scroll back, search for a substring, and jump between matches without losing the live tail. The body is a pkg/pane.Pane (so pgup/pgdn/arrows/mouse-wheel scrolling work out of the box) plus a pkg/filter.Model for the "/-to-search" overlay.

Features:

• Append / AppendLines / Clear streaming API
• MaxLines ring-buffer cap (0 = unbounded)
• Auto-follow: stays glued to the bottom while parked there; pauses when the user scrolls up; "G" jumps to bottom and re-engages follow
• "/" focuses an embedded filter input; typing highlights case-insensitive substring matches inline; enter blurs (keeps the query active for n/N); esc clears
• n / N step to the next / previous match
• g / G jump to top / bottom
• "\" toggles filter mode: when on (and a query is active), only lines containing the query are shown — highlights and n/N jumping still work
• Pane bottom-left status: "FOLLOWING" or "PAUSED", plus "m/n" while a query is active, plus "filter" while filter mode is on

Items pushed in are plain strings, one per line. Render the highlight in place by setting MatchStyle (or via theme.Logview()).

Index

• Constants
• type Model
  • func New(opts Options) Model
  • func (m *Model) Append(line string)
  • func (m *Model) AppendLines(lines []string)
  • func (m *Model) Clear()
  • func (m Model) FilterMode() bool
  • func (m Model) Following() bool
  • func (m Model) Help() []key.Binding
  • func (m Model) Init() tea.Cmd
  • func (m Model) Lines() []string
  • func (m Model) Loading() bool
  • func (m Model) Query() string
  • func (m Model) Searching() bool
  • func (m *Model) SetActiveColor(c lipgloss.TerminalColor)
  • func (m *Model) SetCurrentLineStyle(s lipgloss.Style)
  • func (m *Model) SetDimensions(w, h int)
  • func (m *Model) SetFilterMode(b bool)
  • func (m *Model) SetFocused(b bool)
  • func (m *Model) SetFollow(b bool)
  • func (m *Model) SetInactiveColor(c lipgloss.TerminalColor)
  • func (m *Model) SetLoading(b bool) tea.Cmd
  • func (m *Model) SetLoadingLabel(s string)
  • func (m *Model) SetMatchStyle(s lipgloss.Style)
  • func (m *Model) SetQuery(s string)
  • func (m *Model) SetSpinnerStyle(s lipgloss.Style)
  • func (m *Model) SetTitle(s string)
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
• type Options

Constants

const DefaultMaxLines = 10000

DefaultMaxLines is the safety cap applied when Options.MaxLines is 0 — roughly an hour of moderately busy log output at one line per second.

Types

type Model

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

Model is the logview widget. Embed by value; mutate via the setters.

func New

func New(opts Options) Model

New constructs a logview. Call Update/View from the parent model; push content via Append / AppendLines as it arrives.

func (*Model) Append

func (m *Model) Append(line string)

Append adds one line and, when following, scrolls to the new bottom.

func (*Model) AppendLines

func (m *Model) AppendLines(lines []string)

AppendLines adds a batch of lines and, when following, scrolls to the new bottom — cheaper than calling Append in a loop for large bursts.

func (*Model) Clear

func (m *Model) Clear()

Clear empties the buffer, drops any active query state, and re-engages auto-follow.

func (Model) FilterMode

func (m Model) FilterMode() bool

FilterMode reports whether non-matching lines are currently hidden.

func (Model) Following

func (m Model) Following() bool

Following reports whether the view is glued to the bottom.

func (Model) Help

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

Help returns the keys this logview responds to. While the embedded filter is focused, returns the filter's keys; otherwise the navigation + search bindings appropriate for the current state.

func (Model) Init

func (m Model) Init() tea.Cmd

Init satisfies tea.Model — nothing to kick off.

func (Model) Lines

func (m Model) Lines() []string

Lines returns the buffered lines (newest last). The returned slice aliases the internal buffer — copy it if you intend to retain it.

func (Model) Loading

func (m Model) Loading() bool

Loading reports whether the logview is currently in its loading state.

func (Model) Query

func (m Model) Query() string

Query returns the current search text ("" when no search is active).

func (Model) Searching

func (m Model) Searching() bool

Searching reports whether the embedded filter currently has focus. Mirror this from the enclosing screen's IsCapturingKeys() so the app shell keeps its global keys (q, t, esc) out of the search input.

func (*Model) SetActiveColor

func (m *Model) SetActiveColor(c lipgloss.TerminalColor)

SetActiveColor updates the body pane's active border color.

func (*Model) SetCurrentLineStyle

func (m *Model) SetCurrentLineStyle(s lipgloss.Style)

SetCurrentLineStyle updates the style applied to the "▸ " marker that fronts the line holding the current match.

func (*Model) SetDimensions

func (m *Model) SetDimensions(w, h int)

SetDimensions resizes the logview in place. When searchable, the filter takes 3 rows at the top and the body pane gets the rest.

func (*Model) SetFilterMode

func (m *Model) SetFilterMode(b bool)

SetFilterMode turns filter-only rendering on or off. Has no visible effect until a query is set; takes effect immediately on the next refresh.

func (*Model) SetFocused

func (m *Model) SetFocused(b bool)

SetFocused flips the body pane's focus state so its border reads as active or inactive — useful when embedding logview inside a parent that owns focus cycling.

func (*Model) SetFollow

func (m *Model) SetFollow(b bool)

SetFollow turns auto-follow on or off explicitly. SetFollow(true) jumps to the bottom; SetFollow(false) leaves the scroll position alone.

func (*Model) SetInactiveColor

func (m *Model) SetInactiveColor(c lipgloss.TerminalColor)

SetInactiveColor updates the body pane's inactive border color.

func (*Model) SetLoading

func (m *Model) SetLoading(b bool) tea.Cmd

SetLoading toggles the loading state. When entering, returns the spinner's initial Tick command — propagate it back from your screen's Update so the spinner animates.

func (*Model) SetLoadingLabel

func (m *Model) SetLoadingLabel(s string)

SetLoadingLabel updates the text rendered next to the spinner while loading.

func (*Model) SetMatchStyle

func (m *Model) SetMatchStyle(s lipgloss.Style)

SetMatchStyle updates the highlight style applied to matched substrings.

func (*Model) SetQuery

func (m *Model) SetQuery(s string)

SetQuery sets the search text programmatically (no-op when not Searchable).

func (*Model) SetSpinnerStyle

func (m *Model) SetSpinnerStyle(s lipgloss.Style)

SetSpinnerStyle updates the lipgloss style applied to the spinner glyph.

func (*Model) SetTitle

func (m *Model) SetTitle(s string)

SetTitle sets the pane's top-left title.

func (Model) Update

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

Update handles search ("/"), match jumping (n/N), top/bottom (g/G), and forwards everything else to the body pane (which routes to the embedded viewport for pgup/pgdn/arrows/mouse-wheel). Auto-follow is recomputed from pane.AtBottom() after every key.

func (Model) View

func (m Model) View() string

View stacks the filter (when searchable) above the body pane.

type Options

type Options struct {
	Width, Height int
	// Title sits on the pane's top-left border slot. Defaults to "logs".
	Title string
	// Searchable embeds a filter.Model above the body pane (three rows). If
	// false, "/" is ignored and the full height is used for log content.
	Searchable bool
	// MaxLines caps the number of buffered lines. 0 (default) applies a
	// safety cap of DefaultMaxLines so an open-ended stream can't grow
	// without bound. A positive value sets an explicit cap; -1 disables
	// the cap entirely (use only when the producer is bounded).
	MaxLines int

	// MatchStyle is the lipgloss style applied to matched substrings while
	// a query is active. Pass via theme.Logview() for a sensible default;
	// the zero value renders matches without any visual highlight.
	MatchStyle lipgloss.Style

	// CurrentLineStyle is applied to the entire line holding the current
	// match (the one n/N steps onto), padded out to the pane's inner width
	// so a Background paints the whole row. Set fg/bg/bold/etc as you like;
	// the zero value leaves the row unstyled. theme.Logview() seeds a
	// subtle background by default.
	CurrentLineStyle lipgloss.Style

	// FilterMode controls the initial filter-only state. When true (and a
	// query is active), only matching lines are shown. Toggle at runtime
	// via "\" or SetFilterMode.
	FilterMode bool

	// Pane pass-throughs. See pkg/pane.Options for defaults.
	ActiveColor    lipgloss.TerminalColor
	InactiveColor  lipgloss.TerminalColor
	ActiveBorder   lipgloss.Border
	InactiveBorder lipgloss.Border
	SlotBrackets   pane.SlotBracketStyle
	HScrollbar     bool

	// SpinnerStyle is applied to the spinner glyph rendered while the
	// logview is in its loading state (see SetLoading). Pass via
	// theme.Logview() for a sensible default.
	SpinnerStyle lipgloss.Style
	// LoadingLabel is rendered next to the spinner while loading.
	LoadingLabel string

	// Filter configures the embedded filter. Ignored when Searchable=false.
	Filter filter.Options
}

Options configures a new logview. Zero-value fields fall back to defaults.