focus

Documentation

Overview

Package focus provides a unified focus management system for views with multiple interactive regions (tabs, links, viewport, etc.).

Index

• func FormatHelp(bindings []HelpBinding) string
• func FormatRegionBadge(region *Region) string
• func RenderAccent(content string, focused bool) string
• type FocusChangedMsg
• type HelpBinding
  • func HelpForRegion(regionType RegionType, label string) []HelpBinding
• type Manager
  • func NewManager() *Manager
  • func (m *Manager) Active() *Region
  • func (m *Manager) ActiveID() string
  • func (m *Manager) ActiveType() RegionType
  • func (m *Manager) DisableRegion(id string)
  • func (m *Manager) EnableRegion(id string)
  • func (m *Manager) HandleKey(msg tea.KeyMsg) tea.Msg
  • func (m *Manager) IsActive(id string) bool
  • func (m *Manager) Regions() []Region
  • func (m *Manager) SetActive(id string) bool
  • func (m *Manager) SetRegions(regions []Region)
• type Region
  • func NewDisabledRegion(id string, regionType RegionType, label string) Region
  • func NewRegion(id string, regionType RegionType, label string) Region
• type RegionType
  • func (r RegionType) String() string

Functions

func FormatHelp

func FormatHelp(bindings []HelpBinding) string

FormatHelp formats help bindings as a single string for display. Format: "key: desc • key: desc"

func FormatRegionBadge

func FormatRegionBadge(region *Region) string

FormatRegionBadge returns a styled "▸ Label" badge for the active region. Returns empty string if region is nil or has no label.

func RenderAccent

func RenderAccent(content string, focused bool) string

RenderAccent prepends a blue │ bar to each line when focused. Unfocused content is returned with a single space prefix to maintain alignment.

Types

type FocusChangedMsg

type FocusChangedMsg struct {
	// FromRegion is the previously focused region (nil if first focus)
	FromRegion *Region
	// ToRegion is the newly focused region
	ToRegion *Region
}

FocusChangedMsg is emitted when focus moves to a different region. Views can use this to update visual indicators or help text.

type HelpBinding

type HelpBinding struct {
	Key  string
	Desc string
}

HelpBinding represents a key binding shown in help text.

func HelpForRegion

func HelpForRegion(regionType RegionType, label string) []HelpBinding

HelpForRegion returns context-sensitive help bindings for the given region type. The label parameter can customize the description (e.g., "disk" instead of "item").

type Manager

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

Manager tracks which region has focus within a view and handles Tab key cycling between regions.

func NewManager

func NewManager() *Manager

NewManager creates a new focus manager with no regions. Use SetRegions to configure the available regions.

func (*Manager) Active

func (m *Manager) Active() *Region

Active returns the currently focused region, or nil if no regions exist.

func (*Manager) ActiveID

func (m *Manager) ActiveID() string

ActiveID returns the ID of the currently focused region, or empty string.

func (*Manager) ActiveType

func (m *Manager) ActiveType() RegionType

ActiveType returns the type of the currently focused region. Returns RegionViewport as a safe default if no regions exist.

func (*Manager) DisableRegion

func (m *Manager) DisableRegion(id string)

DisableRegion disables the region with the given ID. If this region was active, focus moves to the next enabled region.

func (*Manager) EnableRegion

func (m *Manager) EnableRegion(id string)

EnableRegion enables the region with the given ID. If no region is currently active, the enabled region becomes active.

func (*Manager) HandleKey

func (m *Manager) HandleKey(msg tea.KeyMsg) tea.Msg

HandleKey processes Tab and Shift+Tab for cycling between regions. Returns a FocusChangedMsg if focus changed, or nil if the key wasn't handled.

func (*Manager) IsActive

func (m *Manager) IsActive(id string) bool

IsActive returns true if the region with the given ID has focus.

func (*Manager) Regions

func (m *Manager) Regions() []Region

Regions returns all configured regions.

func (*Manager) SetActive

func (m *Manager) SetActive(id string) bool

SetActive sets focus to the region with the given ID. Returns true if the region was found and enabled, false otherwise.

func (*Manager) SetRegions

func (m *Manager) SetRegions(regions []Region)

SetRegions configures the focusable regions for this manager. The first enabled region becomes active by default.

type Region

type Region struct {
	// ID uniquely identifies this region within a view
	ID string
	// Type determines which keys are routed to this region
	Type RegionType
	// Label is shown in help text (e.g., "Disks" for a links region)
	Label string
	// Enabled indicates whether this region can receive focus.
	// Disabled regions are skipped during Tab cycling.
	Enabled bool
}

Region represents a focusable area within a view.

func NewDisabledRegion

func NewDisabledRegion(id string, regionType RegionType, label string) Region

NewDisabledRegion creates a region that starts disabled. Useful for regions that become available after data loads.

func NewRegion

func NewRegion(id string, regionType RegionType, label string) Region

NewRegion creates a new focusable region.

type RegionType

type RegionType int

RegionType identifies the behavior of a focusable area. Each type has specific key bindings that apply when focused.

const (
	// RegionViewport scrolls with j/k keys
	RegionViewport RegionType = iota
	// RegionList navigates rows with j/k keys
	RegionList
	// RegionLinks navigates link items with j/k keys
	RegionLinks
	// RegionTabs switches tabs with h/l or 1-9 keys
	RegionTabs
	// RegionForm navigates form fields with j/k keys (future)
	RegionForm
	// RegionButtons navigates buttons with h/l keys (future)
	RegionButtons
)

func (RegionType) String

func (r RegionType) String() string

String returns a human-readable name for the region type.