core

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2025 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package core provides the fundamental types, interfaces, and messages for the vtable library. It defines the shared data structures and contracts used by different components like List and Table, ensuring a consistent and interoperable architecture. This package is the foundation upon which all other vtable modules are built.

Package core provides the fundamental types, interfaces, and messages for the vtable library. It defines the shared data structures and contracts used by different components like List and Table, ensuring a consistent and interoperable architecture. This package is the foundation upon which all other vtable modules are built.

Package core provides the fundamental types, interfaces, and messages for the vtable library. It defines the shared data structures and contracts used by different components like List and Table, ensuring a consistent and interoperable architecture. This package is the foundation upon which all other vtable modules are built.

Package core provides the fundamental types, interfaces, and messages for the vtable library. It defines the shared data structures and contracts used by different components like List and Table, ensuring a consistent and interoperable architecture. This package is the foundation upon which all other vtable modules are built.

Index

Constants

View Source 
const (
	AlignLeft   = 0
	AlignCenter = 1
	AlignRight  = 2
)

Alignment constants for text.

Variables

View Source 
var (
	// StatusColorKey is for storing a color string (e.g., "#FF0000") for status indicators.
	StatusColorKey = MetadataKey[string]{"status_color", "#ffffff", nil}
	// PriorityKey is for storing an integer priority level.
	PriorityKey = MetadataKey[int]{"priority", 0, nil}
	// TooltipKey is for storing a string tooltip.
	TooltipKey = MetadataKey[string]{"tooltip", "", nil}
	// IconKey is for storing an icon character or string.
	IconKey = MetadataKey[string]{"icon", "", nil}
	// BadgeKey is for storing a badge string.
	BadgeKey = MetadataKey[string]{"badge", "", nil}
)

Common metadata keys are predefined for frequent use cases.

Functions

func AccessibilityConfigCmd 

func AccessibilityConfigCmd(screenReader, highContrast, reducedMotion bool) tea.Cmd

AccessibilityConfigCmd creates a command that sends an AccessibilityConfigMsg to configure accessibility features.

func ActiveCellBackgroundColorSetCmd 

func ActiveCellBackgroundColorSetCmd(color string) tea.Cmd

ActiveCellBackgroundColorSetCmd creates a command that sends an ActiveCellBackgroundColorSetMsg to set the active cell's background color.

func ActiveCellIndicationModeSetCmd 

func ActiveCellIndicationModeSetCmd(enabled bool) tea.Cmd

ActiveCellIndicationModeSetCmd creates a command that sends an ActiveCellIndicationModeSetMsg to control the active cell background indicator.

func AnimatedFormatterSetCmd 

func AnimatedFormatterSetCmd(formatter ItemFormatterAnimated[any]) tea.Cmd

AnimatedFormatterSetCmd creates a command that sends an AnimatedFormatterSetMsg to apply a custom animated item formatter to a list.

func AnimationConfigCmd 

func AnimationConfigCmd(config AnimationConfig) tea.Cmd

AnimationConfigCmd creates a command that sends an AnimationConfigMsg to apply a new configuration to the animation engine.

func AnimationStartCmd 

func AnimationStartCmd(animationID string) tea.Cmd

AnimationStartCmd creates a command that sends an AnimationStartMsg to start a specific animation.

func AnimationStopCmd 

func AnimationStopCmd(animationID string) tea.Cmd

AnimationStopCmd creates a command that sends an AnimationStopMsg to stop a specific animation.

func AnimationUpdateCmd 

func AnimationUpdateCmd(updatedAnimations []string) tea.Cmd

AnimationUpdateCmd creates a command that sends an AnimationUpdateMsg to indicate that specific animations have updated.

func AriaLabelCmd 

func AriaLabelCmd(label string) tea.Cmd

AriaLabelCmd returns a command to set the ARIA label for accessibility.

func AriaLabelSetCmd 

func AriaLabelSetCmd(label string) tea.Cmd

AriaLabelSetCmd creates a command that sends an AriaLabelSetMsg to set the ARIA label for a component.

func BatchCmd 

func BatchCmd(messages ...interface{}) tea.Cmd

BatchCmd creates a command that sends a BatchMsg, allowing multiple messages to be dispatched at once.

func BlurCmd 

func BlurCmd() tea.Cmd

BlurCmd creates a command that sends a BlurMsg to remove focus from the component.

func BorderVisibilityCmd 

func BorderVisibilityCmd(visible bool) tea.Cmd

BorderVisibilityCmd creates a command that sends a BorderVisibilityMsg to set the visibility of the table borders.

func BottomBorderSpaceRemovalCmd 

func BottomBorderSpaceRemovalCmd(remove bool) tea.Cmd

BottomBorderSpaceRemovalCmd creates a command that sends a BottomBorderSpaceRemovalMsg to control the removal of space for the bottom border.

func BottomBorderVisibilityCmd 

func BottomBorderVisibilityCmd(visible bool) tea.Cmd

BottomBorderVisibilityCmd creates a command that sends a BottomBorderVisibilityMsg to set the visibility of the bottom border.

func CellAnimatedFormatterSetCmd 

func CellAnimatedFormatterSetCmd(columnIndex int, formatter CellFormatterAnimated) tea.Cmd

CellAnimatedFormatterSetCmd creates a command that sends a CellAnimatedFormatterSetMsg to apply a custom animated formatter to a table column.

func CellAnimationStartCmd 

func CellAnimationStartCmd(rowID string, columnIndex int, animation CellAnimation) tea.Cmd

CellAnimationStartCmd creates a command that sends a CellAnimationStartMsg to start an animation on a specific table cell.

func CellAnimationStopCmd 

func CellAnimationStopCmd(rowID string, columnIndex int) tea.Cmd

CellAnimationStopCmd creates a command that sends a CellAnimationStopMsg to stop an animation on a specific table cell.

func CellFormatterSetCmd 

func CellFormatterSetCmd(columnIndex int, formatter SimpleCellFormatter) tea.Cmd

CellFormatterSetCmd creates a command that sends a CellFormatterSetMsg to apply a custom formatter to a table column.

func ChunkLoadingCompletedCmd 

func ChunkLoadingCompletedCmd(chunkStart int, itemCount int, request DataRequest) tea.Cmd

ChunkLoadingCompletedCmd creates a command that sends a ChunkLoadingCompletedMsg, indicating a chunk has finished loading.

func ChunkLoadingStartedCmd 

func ChunkLoadingStartedCmd(chunkStart int, request DataRequest) tea.Cmd

ChunkLoadingStartedCmd creates a command that sends a ChunkLoadingStartedMsg, indicating a chunk has started to load.

func ChunkSizeSetCmd 

func ChunkSizeSetCmd(size int) tea.Cmd

ChunkSizeSetCmd creates a command that sends a ChunkSizeSetMsg to change the data loading chunk size.

func ChunkUnloadedCmd 

func ChunkUnloadedCmd(chunkStart int) tea.Cmd

ChunkUnloadedCmd creates a command that sends a ChunkUnloadedMsg, indicating a chunk has been unloaded from memory.

func ColumnConstraintsSetCmd 

func ColumnConstraintsSetCmd(columnIndex int, constraints CellConstraint) tea.Cmd

ColumnConstraintsSetCmd creates a command that sends a ColumnConstraintsSetMsg to apply layout constraints to a table column.

func ColumnSetCmd 

func ColumnSetCmd(columns []TableColumn) tea.Cmd

ColumnSetCmd creates a command that sends a ColumnSetMsg to define the columns for a table component.

func ColumnUpdateCmd 

func ColumnUpdateCmd(index int, column TableColumn) tea.Cmd

ColumnUpdateCmd creates a command that sends a ColumnUpdateMsg to update the configuration of a single table column.

func CursorDownCmd 

func CursorDownCmd() tea.Cmd

CursorDownCmd creates a command that sends a CursorDownMsg to move the cursor down.

func CursorLeftCmd 

func CursorLeftCmd() tea.Cmd

CursorLeftCmd creates a command that sends a CursorLeftMsg to move the cursor left.

func CursorRightCmd 

func CursorRightCmd() tea.Cmd

CursorRightCmd creates a command that sends a CursorRightMsg to move the cursor right.

func CursorUpCmd 

func CursorUpCmd() tea.Cmd

CursorUpCmd creates a command that sends a CursorUpMsg to move the cursor up.

func DataChunkErrorCmd 

func DataChunkErrorCmd(startIndex int, err error, request DataRequest) tea.Cmd

DataChunkErrorCmd creates a command that sends a DataChunkErrorMsg, indicating a data chunk failed to load.

func DataChunkLoadedCmd 

func DataChunkLoadedCmd(startIndex int, items []Data[any], request DataRequest) tea.Cmd

DataChunkLoadedCmd creates a command that sends a DataChunkLoadedMsg, indicating a data chunk has been successfully loaded.

func DataChunksRefreshCmd 

func DataChunksRefreshCmd() tea.Cmd

DataChunksRefreshCmd creates a command that sends a DataChunksRefreshMsg to refresh currently loaded chunks while preserving cursor position.

func DataLoadErrorCmd 

func DataLoadErrorCmd(err error) tea.Cmd

DataLoadErrorCmd creates a command that sends a DataLoadErrorMsg, indicating a general data loading error.

func DataRefreshCmd 

func DataRefreshCmd() tea.Cmd

DataRefreshCmd creates a command that sends a DataRefreshMsg to trigger a full data reload.

func DataSourceSetCmd 

func DataSourceSetCmd(dataSource DataSource[any]) tea.Cmd

DataSourceSetCmd creates a command that sends a DataSourceSetMsg to replace the component's data source.

func DataTotalCmd 

func DataTotalCmd(total int) tea.Cmd

DataTotalCmd creates a command that sends a DataTotalMsg, providing the total number of items in the dataset.

func DataTotalRequestCmd 

func DataTotalRequestCmd() tea.Cmd

DataTotalRequestCmd creates a command that sends a DataTotalRequestMsg to explicitly request the total item count from the data source.

func DataTotalUpdateCmd 

func DataTotalUpdateCmd(total int) tea.Cmd

DataTotalUpdateCmd creates a command that sends a DataTotalUpdateMsg to update the total item count while preserving the cursor position.

func DebugEnableCmd 

func DebugEnableCmd(enabled bool) tea.Cmd

DebugEnableCmd creates a command that sends a DebugEnableMsg to enable or disable debugging features.

func DebugLevelSetCmd 

func DebugLevelSetCmd(level DebugLevel) tea.Cmd

DebugLevelSetCmd creates a command that sends a DebugLevelSetMsg to set the debug verbosity level.

func DelayCmd 

func DelayCmd(duration time.Duration, msg tea.Msg) tea.Cmd

DelayCmd creates a command that sends a given message after a specified duration.

func DescriptionSetCmd 

func DescriptionSetCmd(description string) tea.Cmd

DescriptionSetCmd creates a command that sends a DescriptionSetMsg to set the accessible description for a component.

func DestroyCmd 

func DestroyCmd() tea.Cmd

DestroyCmd creates a command that sends a DestroyMsg to clean up a component.

func ErrorCmd 

func ErrorCmd(err error, context string) tea.Cmd

ErrorCmd creates a command that sends an ErrorMsg to report a generic error.

func FilterClearCmd 

func FilterClearCmd(field string) tea.Cmd

FilterClearCmd creates a command that sends a FilterClearMsg to remove a filter.

func FilterSetCmd 

func FilterSetCmd(field string, value any) tea.Cmd

FilterSetCmd creates a command that sends a FilterSetMsg to apply a filter to the data.

func FiltersClearAllCmd 

func FiltersClearAllCmd() tea.Cmd

FiltersClearAllCmd creates a command that sends a FiltersClearAllMsg to remove all active filters.

func FocusCmd 

func FocusCmd() tea.Cmd

FocusCmd creates a command that sends a FocusMsg to give focus to the component.

func FormatterSetCmd 

func FormatterSetCmd(formatter ItemFormatter[any]) tea.Cmd

FormatterSetCmd creates a command that sends a FormatterSetMsg to apply a custom item formatter to a list.

func FullRowHighlightEnableCmd 

func FullRowHighlightEnableCmd(enabled bool) tea.Cmd

FullRowHighlightEnableCmd creates a command that sends a FullRowHighlightEnableMsg to enable or disable full row highlighting mode.

func FullRowHighlightToggleCmd 

func FullRowHighlightToggleCmd() tea.Cmd

FullRowHighlightToggleCmd creates a command that sends a FullRowHighlightToggleMsg to toggle full row highlighting mode.

func GetTypedMetadata 

func GetTypedMetadata[T any](tm *TypedMetadata, key MetadataKey[T]) T

GetTypedMetadata retrieves a value using its type-safe key. If the key is not found or the type does not match, it returns the key's default value.

func GlobalAnimationTickCmd 

func GlobalAnimationTickCmd() tea.Cmd

GlobalAnimationTickCmd creates a command that produces a GlobalAnimationTickMsg at a regular interval, driving the animation engine.

func HeaderCellFormatterSetCmd deprecated 

func HeaderCellFormatterSetCmd(formatter HeaderCellFormatter) tea.Cmd

HeaderCellFormatterSetCmd creates a command that sends a HeaderCellFormatterSetMsg.

Deprecated: Use HeaderFormatterSetCmd instead.

func HeaderFormatterSetCmd 

func HeaderFormatterSetCmd(columnIndex int, formatter SimpleHeaderFormatter) tea.Cmd

HeaderFormatterSetCmd creates a command that sends a HeaderFormatterSetMsg to apply a custom formatter to a table header cell.

func HeaderSeparatorVisibilityCmd 

func HeaderSeparatorVisibilityCmd(visible bool) tea.Cmd

HeaderSeparatorVisibilityCmd creates a command that sends a HeaderSeparatorVisibilityMsg to set the visibility of the header separator line.

func HeaderVisibilityCmd 

func HeaderVisibilityCmd(visible bool) tea.Cmd

HeaderVisibilityCmd creates a command that sends a HeaderVisibilityMsg to set the visibility of the table header.

func HorizontalScrollLeftCmd 

func HorizontalScrollLeftCmd() tea.Cmd

HorizontalScrollLeftCmd creates a command that sends a HorizontalScrollLeftMsg to scroll horizontally left within the current column.

func HorizontalScrollModeToggleCmd 

func HorizontalScrollModeToggleCmd() tea.Cmd

HorizontalScrollModeToggleCmd creates a command that sends a HorizontalScrollModeToggleMsg to cycle through horizontal scroll modes.

func HorizontalScrollPageLeftCmd 

func HorizontalScrollPageLeftCmd() tea.Cmd

HorizontalScrollPageLeftCmd creates a command that sends a HorizontalScrollPageLeftMsg to scroll horizontally left by a page amount.

func HorizontalScrollPageRightCmd 

func HorizontalScrollPageRightCmd() tea.Cmd

HorizontalScrollPageRightCmd creates a command that sends a HorizontalScrollPageRightMsg to scroll horizontally right by a page amount.

func HorizontalScrollResetCmd 

func HorizontalScrollResetCmd() tea.Cmd

HorizontalScrollResetCmd creates a command that sends a HorizontalScrollResetMsg to reset all horizontal scroll offsets.

func HorizontalScrollRightCmd 

func HorizontalScrollRightCmd() tea.Cmd

HorizontalScrollRightCmd creates a command that sends a HorizontalScrollRightMsg to scroll horizontally right within the current column.

func HorizontalScrollScopeToggleCmd 

func HorizontalScrollScopeToggleCmd() tea.Cmd

HorizontalScrollScopeToggleCmd creates a command that sends a HorizontalScrollScopeToggleMsg to toggle horizontal scroll scope.

func HorizontalScrollSmartLeftCmd 

func HorizontalScrollSmartLeftCmd() tea.Cmd

HorizontalScrollSmartLeftCmd creates a command that sends a HorizontalScrollSmartLeftMsg to scroll horizontally left using smart boundaries.

func HorizontalScrollSmartRightCmd 

func HorizontalScrollSmartRightCmd() tea.Cmd

HorizontalScrollSmartRightCmd creates a command that sends a HorizontalScrollSmartRightMsg to scroll horizontally right using smart boundaries.

func HorizontalScrollWordLeftCmd 

func HorizontalScrollWordLeftCmd() tea.Cmd

HorizontalScrollWordLeftCmd creates a command that sends a HorizontalScrollWordLeftMsg to scroll horizontally left by word boundaries.

func HorizontalScrollWordRightCmd 

func HorizontalScrollWordRightCmd() tea.Cmd

HorizontalScrollWordRightCmd creates a command that sends a HorizontalScrollWordRightMsg to scroll horizontally right by word boundaries.

func InitCmd 

func InitCmd() tea.Cmd

InitCmd creates a command that sends an InitMsg to initialize a component.

func ItemAnimationStartCmd 

func ItemAnimationStartCmd(itemID string, animation ListAnimation) tea.Cmd

ItemAnimationStartCmd creates a command that sends an ItemAnimationStartMsg to start an animation on a specific list item.

func ItemAnimationStopCmd 

func ItemAnimationStopCmd(itemID string) tea.Cmd

ItemAnimationStopCmd creates a command that sends an ItemAnimationStopMsg to stop an animation on a specific list item.

func JumpToCmd 

func JumpToCmd(index int) tea.Cmd

JumpToCmd creates a command that sends a JumpToMsg to move the cursor to a specific index.

func JumpToEndCmd 

func JumpToEndCmd() tea.Cmd

JumpToEndCmd creates a command that sends a JumpToEndMsg to move the cursor to the last item.

func JumpToStartCmd 

func JumpToStartCmd() tea.Cmd

JumpToStartCmd creates a command that sends a JumpToStartMsg to move the cursor to the first item.

func KeyMapSetCmd 

func KeyMapSetCmd(keyMap NavigationKeyMap) tea.Cmd

KeyMapSetCmd creates a command that sends a KeyMapSetMsg to apply a new key map.

func LoadingFormatterSetCmd deprecated 

func LoadingFormatterSetCmd(formatter LoadingRowFormatter) tea.Cmd

LoadingFormatterSetCmd creates a command that sends a LoadingFormatterSetMsg.

Deprecated: Use RowFormatterSetCmd instead.

func MaxWidthSetCmd 

func MaxWidthSetCmd(width int) tea.Cmd

MaxWidthSetCmd creates a command that sends a MaxWidthSetMsg to set the maximum width of a list.

func NextColumnCmd 

func NextColumnCmd() tea.Cmd

NextColumnCmd creates a command that sends a NextColumnMsg to move to the next column for horizontal navigation/scrolling focus.

func NoOpCmd 

func NoOpCmd() tea.Cmd

NoOpCmd returns a command that does nothing. It is useful for satisfying function signatures that require a command to be returned, but no action is needed.

func PageDownCmd 

func PageDownCmd() tea.Cmd

PageDownCmd creates a command that sends a PageDownMsg to move the cursor down one page.

func PageLeftCmd 

func PageLeftCmd() tea.Cmd

PageLeftCmd creates a command that sends a PageLeftMsg to move the cursor left one page.

func PageRightCmd 

func PageRightCmd() tea.Cmd

PageRightCmd creates a command that sends a PageRightMsg to move the cursor right one page.

func PageUpCmd 

func PageUpCmd() tea.Cmd

PageUpCmd creates a command that sends a PageUpMsg to move the cursor up one page.

func PerformanceConfigCmd 

func PerformanceConfigCmd(enabled, monitorMemory, monitorRenderTime bool, reportInterval time.Duration) tea.Cmd

PerformanceConfigCmd creates a command that sends a PerformanceConfigMsg to configure performance monitoring.

func PrevColumnCmd 

func PrevColumnCmd() tea.Cmd

PrevColumnCmd creates a command that sends a PrevColumnMsg to move to the previous column for horizontal navigation/scrolling focus.

func RealTimeConfigCmd 

func RealTimeConfigCmd(enabled bool, interval time.Duration) tea.Cmd

RealTimeConfigCmd creates a command that sends a RealTimeConfigMsg to configure real-time updates.

func RealTimeUpdateCmd 

func RealTimeUpdateCmd() tea.Cmd

RealTimeUpdateCmd creates a command that sends a RealTimeUpdateMsg to trigger a real-time data refresh.

func ResetCmd 

func ResetCmd() tea.Cmd

ResetCmd creates a command that sends a ResetMsg to reset a component to its initial state.

func RowAnimationStartCmd 

func RowAnimationStartCmd(rowID string, animation RowAnimation) tea.Cmd

RowAnimationStartCmd creates a command that sends a RowAnimationStartMsg to start an animation on a specific table row.

func RowAnimationStopCmd 

func RowAnimationStopCmd(rowID string) tea.Cmd

RowAnimationStopCmd creates a command that sends a RowAnimationStopMsg to stop an animation on a specific table row.

func RowFormatterSetCmd 

func RowFormatterSetCmd(formatter LoadingRowFormatter) tea.Cmd

RowFormatterSetCmd creates a command that sends a RowFormatterSetMsg to apply a custom formatter for loading placeholder rows.

func SearchClearCmd 

func SearchClearCmd() tea.Cmd

SearchClearCmd creates a command that sends a SearchClearMsg to clear the current search.

func SearchResultCmd 

func SearchResultCmd(results []int, query string, total int) tea.Cmd

SearchResultCmd creates a command that sends a SearchResultMsg containing the results of a search.

func SearchSetCmd 

func SearchSetCmd(query, field string) tea.Cmd

SearchSetCmd creates a command that sends a SearchSetMsg to initiate a search.

func SelectAllCmd 

func SelectAllCmd() tea.Cmd

SelectAllCmd creates a command that sends a SelectAllMsg to select all items.

func SelectClearCmd 

func SelectClearCmd() tea.Cmd

SelectClearCmd creates a command that sends a SelectClearMsg to clear all selections.

func SelectCurrentCmd 

func SelectCurrentCmd() tea.Cmd

SelectCurrentCmd creates a command that sends a SelectCurrentMsg to select the item currently under the cursor.

func SelectRangeCmd 

func SelectRangeCmd(startID, endID string) tea.Cmd

SelectRangeCmd creates a command that sends a SelectRangeMsg to select a range of items between two item IDs.

func SelectToggleCmd 

func SelectToggleCmd(index int) tea.Cmd

SelectToggleCmd creates a command that sends a SelectToggleMsg to toggle the selection state of an item at a specific index.

func SelectionChangedCmd 

func SelectionChangedCmd(selectedIndices []int, selectedIDs []string, totalSelected int) tea.Cmd

SelectionChangedCmd creates a command that sends a SelectionChangedMsg to indicate that the selection state has changed within the data source.

func SelectionModeSetCmd 

func SelectionModeSetCmd(mode SelectionMode) tea.Cmd

SelectionModeSetCmd creates a command that sends a SelectionModeSetMsg to change the component's selection mode.

func SelectionResponseCmd 

func SelectionResponseCmd(success bool, index int, id string, selected bool, operation string, err error, affectedIDs []string) tea.Cmd

SelectionResponseCmd creates a command that sends a SelectionResponseMsg, typically from a data source, to report the result of a selection operation.

func SetComponentBackgroundCmd 

func SetComponentBackgroundCmd(componentType ListComponentType, cursorBg, selectedBg, normalBg lipgloss.Style, applyCursor, applySelected, applyNormal bool) tea.Cmd

SetComponentBackgroundCmd returns a command to configure background styling for a specific component

func SetCursorRowStylingCmd 

func SetCursorRowStylingCmd(enabled bool, background lipgloss.Style) tea.Cmd

SetCursorRowStylingCmd returns a command to enable/disable full row cursor styling

func SetFullRowSelectionCmd 

func SetFullRowSelectionCmd(enabled bool, background lipgloss.Style) tea.Cmd

SetFullRowSelectionCmd returns a command to enable/disable full row selection styling

func SetTypedMetadata 

func SetTypedMetadata[T any](tm *TypedMetadata, key MetadataKey[T], value T) error

SetTypedMetadata stores a value with its associated type-safe key. It runs the key's validator function if one is provided.

func SortAddCmd 

func SortAddCmd(field, direction string) tea.Cmd

SortAddCmd creates a command that sends a SortAddMsg to add a field to a multi-field sort configuration.

func SortRemoveCmd 

func SortRemoveCmd(field string) tea.Cmd

SortRemoveCmd creates a command that sends a SortRemoveMsg to remove a field from the sort configuration.

func SortSetCmd 

func SortSetCmd(field, direction string) tea.Cmd

SortSetCmd creates a command that sends a SortSetMsg to apply a specific sort order to a field.

func SortToggleCmd 

func SortToggleCmd(field string) tea.Cmd

SortToggleCmd creates a command that sends a SortToggleMsg to toggle the sort order of a field.

func SortsClearAllCmd 

func SortsClearAllCmd() tea.Cmd

SortsClearAllCmd creates a command that sends a SortsClearAllMsg to clear all sorting configurations.

func StatusCmd 

func StatusCmd(message string, statusType StatusType) tea.Cmd

StatusCmd creates a command that sends a StatusMsg to display a status message to the user.

func StyleConfigSetCmd 

func StyleConfigSetCmd(config StyleConfig) tea.Cmd

StyleConfigSetCmd creates a command that sends a StyleConfigSetMsg to apply a new style configuration to a list.

func TableThemeSetCmd 

func TableThemeSetCmd(theme Theme) tea.Cmd

TableThemeSetCmd creates a command that sends a TableThemeSetMsg to apply a new theme to a table.

func ThemeSetCmd 

func ThemeSetCmd(theme interface{}) tea.Cmd

ThemeSetCmd creates a command that sends a ThemeSetMsg to apply a new theme.

func TopBorderSpaceRemovalCmd 

func TopBorderSpaceRemovalCmd(remove bool) tea.Cmd

TopBorderSpaceRemovalCmd creates a command that sends a TopBorderSpaceRemovalMsg to control the removal of space for the top border.

func TopBorderVisibilityCmd 

func TopBorderVisibilityCmd(visible bool) tea.Cmd

TopBorderVisibilityCmd creates a command that sends a TopBorderVisibilityMsg to set the visibility of the top border.

func TreeJumpToIndexCmd 

func TreeJumpToIndexCmd(index int, expandParents bool) tea.Cmd

TreeJumpToIndexCmd creates a command that sends a TreeJumpToIndexMsg to move the cursor to a specific index in a tree, with an option to expand parent nodes.

func ValidationErrorCmd 

func ValidationErrorCmd(field string, value any, err error, context string) tea.Cmd

ValidationErrorCmd creates a command that sends a ValidationErrorMsg to report a validation error.

func ViewportConfigCmd 

func ViewportConfigCmd(config ViewportConfig) tea.Cmd

ViewportConfigCmd creates a command that sends a ViewportConfigMsg to apply a new viewport configuration.

func ViewportResizeCmd 

func ViewportResizeCmd(width, height int) tea.Cmd

ViewportResizeCmd creates a command that sends a ViewportResizeMsg to notify a component that its available size has changed.

Types

type AccessibilityConfigMsg 

type AccessibilityConfigMsg struct {
	ScreenReader  bool
	HighContrast  bool
	ReducedMotion bool
}

AccessibilityConfigMsg is a message to configure accessibility features.

type AccessibilityProvider 

type AccessibilityProvider interface {
	// GetAriaLabel returns the ARIA label for the component.
	GetAriaLabel() string
	// SetAriaLabel sets the ARIA label for the component.
	SetAriaLabel(label string)
	// GetDescription returns the accessible description for the component.
	GetDescription() string
	// SetDescription sets the accessible description for the component.
	SetDescription(desc string)

	// IsHighContrast returns true if high contrast mode is enabled.
	IsHighContrast() bool
	// SetHighContrast enables or disables high contrast mode.
	SetHighContrast(enabled bool) tea.Cmd

	// IsReducedMotion returns true if reduced motion mode is enabled.
	IsReducedMotion() bool
	// SetReducedMotion enables or disables reduced motion mode.
	SetReducedMotion(enabled bool) tea.Cmd

	// GetKeyboardShortcuts returns the list of available keyboard shortcuts.
	GetKeyboardShortcuts() []KeyboardShortcut
	// SetKeyboardShortcuts sets a new list of keyboard shortcuts.
	SetKeyboardShortcuts(shortcuts []KeyboardShortcut) tea.Cmd
}

AccessibilityProvider defines the contract for managing accessibility features.

type ActiveCellBackgroundColorSetMsg 

type ActiveCellBackgroundColorSetMsg struct {
	Color string // lipgloss color value
}

ActiveCellBackgroundColorSetMsg is a message to set the background color of the active cell in a table.

type ActiveCellIndicationModeSetMsg 

type ActiveCellIndicationModeSetMsg struct {
	Enabled bool // Simple boolean: enabled or disabled
}

ActiveCellIndicationModeSetMsg is a message to set the active cell indication mode for tables.

type AnimatedFormatterSetMsg 

type AnimatedFormatterSetMsg struct {
	Formatter ItemFormatterAnimated[any]
}

AnimatedFormatterSetMsg is a message to set a custom animated item formatter for a list component.

type Animation 

type Animation struct {
	// State holds the current values for the animation (e.g., opacity, position).
	State map[string]any
	// Triggers define when the animation should be updated.
	Triggers []RefreshTrigger
	// LastRender is the timestamp of the last render.
	LastRender time.Time
	// IsVisible indicates if the animated item is currently in the viewport.
	IsVisible bool
}

Animation represents a single animation instance.

type AnimationConfig 

type AnimationConfig struct {
	// Enabled globally enables or disables animations.
	Enabled bool
	// ReducedMotion, when true, disables non-essential animations for accessibility.
	ReducedMotion bool
	// MaxAnimations is the maximum number of concurrent animations.
	MaxAnimations int
	// BatchUpdates, when true, batches multiple animation updates into a single message.
	BatchUpdates bool
	// TickInterval is the time between global animation ticks.
	TickInterval time.Duration
}

AnimationConfig controls the global behavior of the animation engine.

func DefaultAnimationConfig 

func DefaultAnimationConfig() AnimationConfig

DefaultAnimationConfig returns a sensible default configuration for animations.

type AnimationConfigMsg 

type AnimationConfigMsg struct {
	Config AnimationConfig
}

AnimationConfigMsg is a message to set a new configuration for the animation engine.

type AnimationEngine 

type AnimationEngine interface {
	// StartLoop starts the animation engine's update loop, returning a command
	// that produces tick messages.
	StartLoop() tea.Cmd
	// StopLoop stops the animation engine's update loop.
	StopLoop()
	// IsRunning returns true if the animation loop is active.
	IsRunning() bool

	// RegisterAnimation registers a new animation with the engine.
	RegisterAnimation(id string, triggers []RefreshTrigger, initialState map[string]any) tea.Cmd
	// UnregisterAnimation removes an animation from the engine.
	UnregisterAnimation(id string) tea.Cmd
	// SetVisible notifies the engine whether an animated item is currently visible.
	SetVisible(id string, visible bool)
	// IsVisible checks if an animated item is marked as visible.
	IsVisible(id string) bool

	// GetAnimationState retrieves the current state of a specific animation.
	GetAnimationState(id string) map[string]any
	// UpdateAnimationState updates the state of a specific animation.
	UpdateAnimationState(id string, newState map[string]any)
	// HasUpdates returns true if any animations have changed since the last check.
	HasUpdates() bool
	// ClearDirtyFlags resets the update flags for all animations.
	ClearDirtyFlags()

	// GetConfig returns the current animation configuration.
	GetConfig() AnimationConfig
	// UpdateConfig applies a new configuration to the engine.
	UpdateConfig(config AnimationConfig) tea.Cmd

	// ProcessGlobalTick processes a global tick message to update timer-based animations.
	ProcessGlobalTick(msg GlobalAnimationTickMsg) tea.Cmd
	// ProcessEvent processes an event, triggering any event-based animations.
	ProcessEvent(event string) []string
	// CheckConditionalTriggers evaluates all conditional triggers.
	CheckConditionalTriggers() []string

	// Cleanup releases any resources used by the animation engine.
	Cleanup()
}

AnimationEngine defines the contract for an animation management system. It handles the registration, state updates, and rendering lifecycle of animations.

type AnimationStartMsg 

type AnimationStartMsg struct {
	AnimationID string
}

AnimationStartMsg is a message to start a specific registered animation.

type AnimationState 

type AnimationState struct {
	// ID is the unique identifier for the animation.
	ID string
	// State holds the animation's current values.
	State map[string]any
	// Triggers define when the animation updates.
	Triggers []RefreshTrigger
	// LastUpdate is the timestamp of the last state change.
	LastUpdate time.Time
	// NextUpdate is the scheduled time for the next update (for timer triggers).
	NextUpdate time.Time
	// IsActive indicates if the animation is currently running.
	IsActive bool
	// IsVisible indicates if the animated item is in the viewport.
	IsVisible bool
	// IsDirty is true if the animation state has changed since the last render.
	IsDirty bool
}

AnimationState holds the complete state of a managed animation.

type AnimationStopMsg 

type AnimationStopMsg struct {
	AnimationID string
}

AnimationStopMsg is a message to stop a specific running animation.

type AnimationUpdateMsg 

type AnimationUpdateMsg struct {
	UpdatedAnimations []string
}

AnimationUpdateMsg is a message indicating that one or more animations have been updated and may require a re-render.

type AriaLabelSetMsg 

type AriaLabelSetMsg struct {
	Label string
}

AriaLabelSetMsg is a message to set the ARIA label for a component, improving screen reader support.

type BatchMsg 

type BatchMsg struct {
	Messages []interface{}
}

BatchMsg is a message that wraps multiple other messages, allowing them to be processed in a single update cycle.

func Batch 

func Batch(messages ...interface{}) BatchMsg

Batch creates a new BatchMsg from a variadic list of messages.

type BlurMsg 

type BlurMsg struct{}

BlurMsg is a message to remove focus from the component, making it inactive.

type BorderChars 

type BorderChars struct {
	Horizontal  string
	Vertical    string
	TopLeft     string
	TopRight    string
	BottomLeft  string
	BottomRight string
	TopT        string
	BottomT     string
	LeftT       string
	RightT      string
	Cross       string
}

BorderChars defines the characters used for drawing table borders.

func DefaultBorderChars 

func DefaultBorderChars() BorderChars

DefaultBorderChars returns the default characters used for table borders.

type BorderVisibilityMsg 

type BorderVisibilityMsg struct {
	Visible bool
}

BorderVisibilityMsg is a message to set the visibility of table borders.

type BottomBorderSpaceRemovalMsg 

type BottomBorderSpaceRemovalMsg struct {
	Remove bool
}

BottomBorderSpaceRemovalMsg is a message to control whether the space for the bottom border is completely removed when it's not visible.

type BottomBorderVisibilityMsg 

type BottomBorderVisibilityMsg struct {
	Visible bool
}

BottomBorderVisibilityMsg is a message to set the visibility of the table's bottom border.

type BoundingArea 

type BoundingArea struct {
	// StartIndex is the absolute start index of the bounding area.
	StartIndex int
	// EndIndex is the absolute end index (inclusive) of the bounding area.
	EndIndex int
	// ChunkStart is the start index of the first chunk within the bounding area.
	ChunkStart int
	// ChunkEnd is the boundary for the last chunk in the area (exclusive).
	ChunkEnd int
}

BoundingArea represents the area around the viewport where data chunks should be pre-emptively loaded to ensure smooth scrolling. It is defined by absolute item indices and chunk boundaries.

type CellAnimatedFormatterSetMsg 

type CellAnimatedFormatterSetMsg struct {
	ColumnIndex int
	Formatter   CellFormatterAnimated
}

CellAnimatedFormatterSetMsg is a message to set a custom animated cell formatter for a table column.

type CellAnimation 

type CellAnimation struct {
	// RowID is the ID of the row containing the cell.
	RowID string
	// ColumnIndex is the index of the column containing the cell.
	ColumnIndex int
	// AnimationType is the type of animation.
	AnimationType string
	// State holds the animation's current values.
	State map[string]any
	// Triggers define when the animation should update.
	Triggers []RefreshTrigger
}

CellAnimation represents an animation for a table cell.

type CellAnimationStartMsg 

type CellAnimationStartMsg struct {
	RowID       string
	ColumnIndex int
	Animation   CellAnimation
}

CellAnimationStartMsg is a message to start an animation for a specific table cell.

type CellAnimationStopMsg 

type CellAnimationStopMsg struct {
	RowID       string
	ColumnIndex int
}

CellAnimationStopMsg is a message to stop an animation for a specific table cell.

type CellConstraint 

type CellConstraint struct {
	// Width is the exact width the cell must occupy.
	Width int
	// Height is the exact height the cell must occupy (usually 1 for tables).
	Height int
	// Alignment specifies text alignment (AlignLeft, AlignCenter, AlignRight).
	Alignment int
	// Padding defines the padding within the cell.
	Padding PaddingConfig
	// MaxLines is the maximum number of lines for multi-line content.
	MaxLines int
}

CellConstraint defines the dimensional and alignment constraints for a table cell.

type CellFormatter deprecated 

type CellFormatter func(
	cellValue string,
	rowIndex int,
	columnIndex int,
	column TableColumn,
	ctx RenderContext,
	isCursor bool,
	isSelected bool,
	isTopThreshold bool,
	isBottomThreshold bool,
) string

CellFormatter defines how a single table cell is rendered.

Deprecated: Use SimpleCellFormatter instead, which simplifies the function signature and automatically handles truncation.

type CellFormatterAnimated 

type CellFormatterAnimated func(
	cellValue string,
	rowIndex int,
	columnIndex int,
	column TableColumn,
	ctx RenderContext,
	animationState map[string]any,
	isCursor bool,
	isSelected bool,
	isTopThreshold bool,
	isBottomThreshold bool,
) CellRenderResult

CellFormatterAnimated is a function that defines how a table cell is rendered with animation support. It returns a CellRenderResult containing the string content and animation metadata.

type CellFormatterSetMsg 

type CellFormatterSetMsg struct {
	ColumnIndex int // -1 applies to all columns
	Formatter   SimpleCellFormatter
}

CellFormatterSetMsg is a message to set a custom cell formatter for a table column.

type CellRenderResult 

type CellRenderResult struct {
	// Content is the rendered cell content.
	Content string

	// ActualWidth is the actual width of the rendered content.
	ActualWidth int

	// ActualHeight is the actual height of the rendered content.
	ActualHeight int

	// Overflow indicates whether the content was truncated or wrapped.
	Overflow bool

	// RefreshTriggers specify when this cell should be re-rendered.
	RefreshTriggers []RefreshTrigger

	// AnimationState stores state between renders for this specific cell.
	AnimationState map[string]any

	// Error contains any rendering error.
	Error error

	// Fallback content to use if a rendering error occurs.
	Fallback string
}

CellRenderResult contains the result of a table cell rendering operation, including the content and its dimensional properties.

type Chunk 

type Chunk[T any] struct {
	// StartIndex is the absolute index of the first item in the chunk.
	StartIndex int

	// EndIndex is the absolute index of the last item in the chunk.
	EndIndex int

	// Items is the slice of Data items contained in the chunk.
	Items []Data[T]

	// LoadedAt is the timestamp when this chunk was loaded into memory.
	LoadedAt time.Time

	// Request is the DataRequest that was used to load this chunk, useful for
	// validation and debugging.
	Request DataRequest
}

Chunk represents a block of data loaded from a DataSource. Components use chunks to manage large datasets efficiently without keeping everything in memory.

type ChunkInfo 

type ChunkInfo struct {
	// StartIndex is the absolute index of the first item in the chunk.
	StartIndex int

	// EndIndex is the absolute index of the last item in the chunk.
	EndIndex int

	// ItemCount is the number of items in the chunk.
	ItemCount int
}

ChunkInfo provides metadata about a loaded chunk.

type ChunkLoadingCompletedMsg 

type ChunkLoadingCompletedMsg struct {
	ChunkStart int
	ItemCount  int
	Request    DataRequest
}

ChunkLoadingCompletedMsg is a message indicating that a data chunk has finished loading, successfully or not.

type ChunkLoadingStartedMsg 

type ChunkLoadingStartedMsg struct {
	ChunkStart int
	Request    DataRequest
}

ChunkLoadingStartedMsg is a message indicating that a request to load a data chunk has been initiated. Useful for showing loading indicators.

type ChunkSizeSetMsg 

type ChunkSizeSetMsg struct {
	Size int
}

ChunkSizeSetMsg is a message to set the chunk size for data loading.

type ChunkUnloadedMsg 

type ChunkUnloadedMsg struct {
	ChunkStart int
}

ChunkUnloadedMsg is a message indicating that a data chunk has been unloaded from memory, usually as part of a cache-clearing strategy.

type ColumnConstraintsSetMsg 

type ColumnConstraintsSetMsg struct {
	ColumnIndex int
	Constraints CellConstraint
}

ColumnConstraintsSetMsg is a message to set layout constraints for a table column.

type ColumnSetMsg 

type ColumnSetMsg struct {
	Columns []TableColumn
}

ColumnSetMsg is a message to set the columns for a table component.

type ColumnUpdateMsg 

type ColumnUpdateMsg struct {
	Index  int
	Column TableColumn
}

ColumnUpdateMsg is a message to update the configuration of a single table column.

type Configurable 

type Configurable interface {
	// GetConfig returns the component's current configuration.
	GetConfig() any
	// SetConfig applies a new configuration and returns a command.
	SetConfig(config any) tea.Cmd
	// ValidateConfig checks if a given configuration is valid.
	ValidateConfig(config any) error
	// ResetToDefaults resets the component's configuration to its default
	// values and returns a command.
	ResetToDefaults() tea.Cmd
}

Configurable represents a component whose configuration can be managed.

type CursorDownMsg 

type CursorDownMsg struct{}

CursorDownMsg is a message sent to move the cursor down by one position.

type CursorLeftMsg 

type CursorLeftMsg struct{}

CursorLeftMsg is a message sent to move the cursor left by one position.

type CursorRightMsg 

type CursorRightMsg struct{}

CursorRightMsg is a message sent to move the cursor right by one position.

type CursorUpMsg 

type CursorUpMsg struct{}

CursorUpMsg is a message sent to move the cursor up by one position.

type Data 

type Data[T any] struct {
	// ID is a stable unique identifier for this item, crucial for state
	// management.
	ID string

	// Item is the actual data item of type T.
	Item T

	// Selected indicates if this item is currently selected.
	Selected bool

	// Metadata contains custom, type-safe rendering metadata for advanced styling
	// or behavior.
	Metadata TypedMetadata

	// Disabled indicates if this item should be rendered as disabled and be
	// non-interactive.
	Disabled bool

	// Hidden indicates if this item should be hidden from view.
	Hidden bool

	// Error contains any error state associated with this item, which can be
	// used for special styling.
	Error error

	// Loading indicates if this item is currently in a loading state, for
	// example, if its data is being fetched.
	Loading bool
}

Data is a generic wrapper for any data item managed by a vtable component. It augments the original item with state information essential for rendering and interaction, such as selection status, loading state, and associated errors.

type DataChunkErrorMsg 

type DataChunkErrorMsg struct {
	StartIndex int
	Error      error
	Request    DataRequest
}

DataChunkErrorMsg is a message sent by a DataSource when a requested chunk of data failed to load.

type DataChunkLoadedMsg 

type DataChunkLoadedMsg struct {
	StartIndex int
	Items      []Data[any]
	Request    DataRequest // The original request, for validation
}

DataChunkLoadedMsg is a message sent by a DataSource when a requested chunk of data has been successfully loaded.

type DataChunksRefreshMsg 

type DataChunksRefreshMsg struct{}

DataChunksRefreshMsg is a message sent to refresh only the currently loaded data chunks, preserving the cursor position. This is useful for reflecting state changes (like selection) without a full reload.

type DataLoadErrorMsg 

type DataLoadErrorMsg struct {
	Error error
}

DataLoadErrorMsg is a message indicating a general error occurred during data loading, not specific to a single chunk.

type DataRefreshMsg 

type DataRefreshMsg struct{}

DataRefreshMsg is a message sent to trigger a full refresh of the component's data, including reloading the total count and all visible chunks.

type DataRequest 

type DataRequest struct {
	// Start is the index of the first item to return.
	Start int

	// Count is the number of items to return.
	Count int

	// SortFields specifies the fields to sort by, in order of priority.
	SortFields []string

	// SortDirections specifies the sort directions ("asc" or "desc")
	// corresponding to SortFields.
	SortDirections []string

	// Filters is a map of field names to their corresponding filter values.
	Filters map[string]any
}

DataRequest represents a request for a segment of data from a DataSource. It supports pagination, sorting, and filtering.

type DataSource 

type DataSource[T any] interface {
	// LoadChunk requests a chunk of data from the data source. It should return a
	// tea.Cmd that, when executed, produces either a DataChunkLoadedMsg on
	// success or a DataChunkErrorMsg on failure.
	LoadChunk(request DataRequest) tea.Cmd

	// GetTotal requests the total number of items available in the data source.
	// It should return a tea.Cmd that resolves to a DataTotalMsg.
	GetTotal() tea.Cmd

	// RefreshTotal requests an updated total count from the data source. This is
	// useful when the dataset size changes dynamically. It should return a
	// tea.Cmd that resolves to a DataTotalMsg.
	RefreshTotal() tea.Cmd

	// SetSelected sends a command to update the selection state of an item at a
	// specific index.
	SetSelected(index int, selected bool) tea.Cmd
	// SetSelectedByID sends a command to update the selection state of an item
	// with a specific ID.
	SetSelectedByID(id string, selected bool) tea.Cmd
	// SelectAll sends a command to select all items in the data source.
	SelectAll() tea.Cmd
	// ClearSelection sends a command to clear all selections.
	ClearSelection() tea.Cmd
	// SelectRange sends a command to select a range of items between two indices.
	SelectRange(startIndex, endIndex int) tea.Cmd

	// GetItemID returns the stable, unique ID for a given data item. This is a
	// pure function and can be called directly.
	GetItemID(item T) string
}

DataSource defines the contract for providing data to vtable components like List and Table. It uses a command-based, asynchronous pattern to load data, preventing the UI from blocking. Implementations of this interface are responsible for fetching data from any source, such as a database, an API, or an in-memory slice.

type DataSourceSetMsg 

type DataSourceSetMsg struct {
	DataSource DataSource[any]
}

DataSourceSetMsg is a message sent to replace the component's current DataSource with a new one.

type DataTotalMsg 

type DataTotalMsg struct {
	Total int
}

DataTotalMsg is a message sent by a DataSource containing the total number of items in the dataset.

type DataTotalRequestMsg 

type DataTotalRequestMsg struct{}

DataTotalRequestMsg is a message sent to explicitly request the total item count from the DataSource.

type DataTotalUpdateMsg 

type DataTotalUpdateMsg struct {
	Total int
}

DataTotalUpdateMsg is a message sent to update the total number of items while preserving the current cursor and viewport position.

type DebugEnableMsg 

type DebugEnableMsg struct {
	Enabled bool
}

DebugEnableMsg is a message to enable or disable debugging features.

type DebugLevel 

type DebugLevel int

DebugLevel defines the verbosity of debugging information. 

const (
	DebugLevelNone DebugLevel = iota
	DebugLevelBasic
	DebugLevelDetailed
	DebugLevelVerbose
)

Constants for different debug levels.

type DebugLevelSetMsg 

type DebugLevelSetMsg struct {
	Level DebugLevel
}

DebugLevelSetMsg is a message to set the verbosity level for debugging output.

type Debugger 

type Debugger interface {
	// GetDebugInfo returns a string with general debugging information.
	GetDebugInfo() string
	// GetStateInfo returns a string with detailed state information.
	GetStateInfo() string
	// GetChunkInfo returns a string with information about loaded data chunks.
	GetChunkInfo() string
	// GetAnimationInfo returns a string with information about active animations.
	GetAnimationInfo() string

	// EnableDebug toggles the debugging mode.
	EnableDebug(enabled bool)
	// IsDebugEnabled returns true if debugging is enabled.
	IsDebugEnabled() bool
	// SetDebugLevel sets the verbosity of debugging information.
	SetDebugLevel(level DebugLevel)
	// GetDebugLevel returns the current debug level.
	GetDebugLevel() DebugLevel
}

Debugger provides methods for accessing internal debugging information.

type DescriptionSetMsg 

type DescriptionSetMsg struct {
	Description string
}

DescriptionSetMsg is a message to set the accessible description for a component.

type DestroyMsg 

type DestroyMsg struct{}

DestroyMsg is a message to trigger the cleanup and resource release of a component.

type ErrorHandler 

type ErrorHandler interface {
	// HandleError processes and stores an error.
	HandleError(err error)
	// GetLastError returns the most recent error.
	GetLastError() error
	// ClearErrors removes all stored errors.
	ClearErrors()
	// HasErrors returns true if there are any stored errors.
	HasErrors() bool

	// GetErrorCount returns the total number of stored errors.
	GetErrorCount() int
	// GetErrors returns all stored errors.
	GetErrors() []error
}

ErrorHandler defines the contract for components that manage error states.

type ErrorMsg 

type ErrorMsg struct {
	Error   error
	Context string
}

ErrorMsg is a message representing a generic error that has occurred.

type EventHandler 

type EventHandler interface {
	// OnSelect registers a callback to be invoked when an item is selected.
	OnSelect(callback func(item any, index int))
	// OnDeselect registers a callback to be invoked when an item is deselected.
	OnDeselect(callback func(item any, index int))
	// OnSelectionChange registers a callback to be invoked when the overall
	// selection changes.
	OnSelectionChange(callback func(selectedItems []any))

	// OnCursorMove registers a callback for when the cursor moves.
	OnCursorMove(callback func(from, to int))
	// OnScroll registers a callback for when the viewport scrolls.
	OnScroll(callback func(state ViewportState))

	// OnDataLoad registers a callback for when data is successfully loaded.
	OnDataLoad(callback func(items []any))
	// OnDataError registers a callback for when a data loading error occurs.
	OnDataError(callback func(err error))

	// OnFocus registers a callback for when the component gains focus.
	OnFocus(callback func())
	// OnBlur registers a callback for when the component loses focus.
	OnBlur(callback func())
}

EventHandler defines callbacks for various component events.

type FilterClearMsg 

type FilterClearMsg struct {
	Field string
}

FilterClearMsg is a message to remove a filter from a specific data field.

type FilterSetMsg 

type FilterSetMsg struct {
	Field string
	Value any
}

FilterSetMsg is a message to apply or update a filter on a specific data field.

type FiltersClearAllMsg 

type FiltersClearAllMsg struct{}

FiltersClearAllMsg is a message to remove all active filters.

type FocusMsg 

type FocusMsg struct{}

FocusMsg is a message to give focus to the component, making it active.

type FocusState 

type FocusState struct {
	// HasFocus is true if the component is currently focused.
	HasFocus bool
	// FocusedCell identifies the currently focused cell in a table, typically in
	// "rowID:columnField" format.
	FocusedCell string
}

FocusState contains information about the component's focus state.

type FormatterSetMsg 

type FormatterSetMsg struct {
	Formatter ItemFormatter[any]
}

FormatterSetMsg is a message to set a custom item formatter for a list component.

type FullRowHighlightEnableMsg 

type FullRowHighlightEnableMsg struct {
	Enabled bool
}

FullRowHighlightEnableMsg enables or disables full row highlighting mode.

type FullRowHighlightToggleMsg 

type FullRowHighlightToggleMsg struct{}

FullRowHighlightToggleMsg toggles full row highlighting mode.

type GlobalAnimationTickMsg 

type GlobalAnimationTickMsg struct {
	Timestamp time.Time
}

GlobalAnimationTickMsg is a message sent periodically by the animation engine to drive time-based animations.

type HeaderCellFormatter deprecated 

type HeaderCellFormatter func(
	column TableColumn,
	columnIndex int,
	ctx RenderContext,
) string

HeaderCellFormatter defines how an individual header cell is rendered.

Deprecated: Use SimpleHeaderFormatter instead for a simpler API and automatic truncation.

type HeaderCellFormatterSetMsg deprecated 

type HeaderCellFormatterSetMsg struct {
	Formatter HeaderCellFormatter
}

HeaderCellFormatterSetMsg is a message to set a custom header cell formatter.

Deprecated: Use HeaderFormatterSetMsg instead.

type HeaderFormatter 

type HeaderFormatter func(
	columns []TableColumn,
	ctx RenderContext,
) string

HeaderFormatter is a function that defines how the entire table header is rendered from its constituent column titles.

type HeaderFormatterSetMsg 

type HeaderFormatterSetMsg struct {
	ColumnIndex int
	Formatter   SimpleHeaderFormatter
}

HeaderFormatterSetMsg is a message to set a custom header formatter for a table column.

type HeaderSeparatorVisibilityMsg 

type HeaderSeparatorVisibilityMsg struct {
	Visible bool
}

HeaderSeparatorVisibilityMsg is a message to set the visibility of the separator line between the header and the table body.

type HeaderVisibilityMsg 

type HeaderVisibilityMsg struct {
	Visible bool
}

HeaderVisibilityMsg is a message to set the visibility of the table header.

type HorizontalScrollLeftMsg 

type HorizontalScrollLeftMsg struct{}

HorizontalScrollLeftMsg is a message sent to scroll horizontally left within the current column.

type HorizontalScrollModeToggleMsg 

type HorizontalScrollModeToggleMsg struct{}

HorizontalScrollModeToggleMsg is a message sent to cycle through horizontal scroll modes (character/word/smart).

type HorizontalScrollPageLeftMsg 

type HorizontalScrollPageLeftMsg struct{}

HorizontalScrollPageLeftMsg is a message sent to scroll horizontally left by a page amount.

type HorizontalScrollPageRightMsg 

type HorizontalScrollPageRightMsg struct{}

HorizontalScrollPageRightMsg is a message sent to scroll horizontally right by a page amount.

type HorizontalScrollResetMsg 

type HorizontalScrollResetMsg struct{}

HorizontalScrollResetMsg is a message sent to reset all horizontal scroll offsets.

type HorizontalScrollRightMsg 

type HorizontalScrollRightMsg struct{}

HorizontalScrollRightMsg is a message sent to scroll horizontally right within the current column.

type HorizontalScrollScopeToggleMsg 

type HorizontalScrollScopeToggleMsg struct{}

HorizontalScrollScopeToggleMsg is a message sent to toggle horizontal scroll scope (current row/all rows).

type HorizontalScrollSmartLeftMsg 

type HorizontalScrollSmartLeftMsg struct{}

HorizontalScrollSmartLeftMsg is a message sent to scroll horizontally left using smart boundaries.

type HorizontalScrollSmartRightMsg 

type HorizontalScrollSmartRightMsg struct{}

HorizontalScrollSmartRightMsg is a message sent to scroll horizontally right using smart boundaries.

type HorizontalScrollWordLeftMsg 

type HorizontalScrollWordLeftMsg struct{}

HorizontalScrollWordLeftMsg is a message sent to scroll horizontally left by word boundaries.

type HorizontalScrollWordRightMsg 

type HorizontalScrollWordRightMsg struct{}

HorizontalScrollWordRightMsg is a message sent to scroll horizontally right by word boundaries.

type InitMsg 

type InitMsg struct{}

InitMsg is a message to trigger the initial state setup of a component.

type ItemAnimationStartMsg 

type ItemAnimationStartMsg struct {
	ItemID    string
	Animation ListAnimation
}

ItemAnimationStartMsg is a message to start an animation for a specific list item.

type ItemAnimationStopMsg 

type ItemAnimationStopMsg struct {
	ItemID string
}

ItemAnimationStopMsg is a message to stop an animation for a specific list item.

type ItemFormatter 

type ItemFormatter[T any] func(
	data Data[T],
	index int,
	ctx RenderContext,
	isCursor bool,
	isTopThreshold bool,
	isBottomThreshold bool,
) string

ItemFormatter is a function that defines how a single list item is rendered into a string. It receives the item's data, its state (cursor, selection), and the render context.

type ItemFormatterAnimated 

type ItemFormatterAnimated[T any] func(
	data Data[T],
	index int,
	ctx RenderContext,
	animationState map[string]any,
	isCursor bool,
	isTopThreshold bool,
	isBottomThreshold bool,
) RenderResult

ItemFormatterAnimated is a function that defines how a list item is rendered with animation support. It returns a RenderResult containing the string content and animation metadata.

type JumpToEndMsg 

type JumpToEndMsg struct{}

JumpToEndMsg is a message sent to move the cursor to the last item in the dataset.

type JumpToMsg 

type JumpToMsg struct {
	Index int
}

JumpToMsg is a message sent to move the cursor to a specific absolute index.

type JumpToStartMsg 

type JumpToStartMsg struct{}

JumpToStartMsg is a message sent to move the cursor to the first item in the dataset.

type KeyMapSetMsg 

type KeyMapSetMsg struct {
	KeyMap NavigationKeyMap
}

KeyMapSetMsg is a message to apply a new key map for navigation and actions.

type KeyboardShortcut 

type KeyboardShortcut struct {
	Key         string
	Description string
	Action      string
}

KeyboardShortcut represents a single keyboard shortcut and its description.

type ListAnimation 

type ListAnimation struct {
	// ItemID is the ID of the list item to animate.
	ItemID string
	// AnimationType is the type of animation (e.g., "fade", "slide").
	AnimationType string
	// State holds the animation's current values.
	State map[string]any
	// Triggers define when the animation should update.
	Triggers []RefreshTrigger
}

ListAnimation represents an animation for a list item.

type ListBackgroundConfig 

type ListBackgroundConfig struct {
	Enabled           bool
	Style             lipgloss.Style
	ApplyToComponents []ListComponentType
	Mode              ListBackgroundMode
}

ListBackgroundConfig configures the background styling component.

type ListBackgroundMode 

type ListBackgroundMode int

ListBackgroundMode defines how background styling is applied. 

const (
	// ListBackgroundEntireLine applies the background to the entire line.
	ListBackgroundEntireLine ListBackgroundMode = iota
	// ListBackgroundSelectiveComponents applies the background to a specified
	// subset of components.
	ListBackgroundSelectiveComponents
	// ListBackgroundContentOnly applies the background only to the content component.
	ListBackgroundContentOnly
	// ListBackgroundIndicatorOnly applies the background only to the cursor
	// component.
	ListBackgroundIndicatorOnly
)

Constants for list background rendering modes.

type ListComponentContext 

type ListComponentContext struct {
	// Item is the data for the item being rendered.
	Item Data[any]
	// Index is the absolute index of the item in the dataset.
	Index int
	// IsCursor is true if the item is under the cursor.
	IsCursor bool
	// IsSelected is true if the item is selected.
	IsSelected bool
	// IsThreshold is true if the item is at a scroll threshold.
	IsThreshold bool

	// RenderContext provides global rendering information.
	RenderContext RenderContext

	// ComponentData is a map containing the rendered output of preceding
	// components in the pipeline.
	ComponentData map[ListComponentType]string

	// ListConfig holds the current rendering configuration for the list.
	ListConfig ListRenderConfig
}

ListComponentContext provides all necessary data for a ListRenderComponent to render itself. It is passed to the Render method of each component.

type ListComponentType 

type ListComponentType string

ListComponentType is a unique identifier for each type of list rendering component. 

const (
	ListComponentCursor      ListComponentType = "cursor"
	ListComponentPreSpacing  ListComponentType = "pre_spacing"
	ListComponentEnumerator  ListComponentType = "enumerator"
	ListComponentContent     ListComponentType = "content"
	ListComponentPostSpacing ListComponentType = "post_spacing"
	ListComponentBackground  ListComponentType = "background"
)

Constants for all available list component types.

type ListConfig 

type ListConfig struct {
	// ViewportConfig defines the viewport behavior.
	ViewportConfig ViewportConfig

	// StyleConfig defines the styles for list items.
	StyleConfig StyleConfig

	// RenderConfig defines the component-based rendering pipeline.
	RenderConfig ListRenderConfig

	// SelectionMode defines the selection behavior.
	SelectionMode SelectionMode

	// KeyMap defines the keybindings for navigation and actions.
	KeyMap NavigationKeyMap

	// MaxWidth is the maximum width of the list.
	MaxWidth int
}

ListConfig contains all configuration options for a list component.

type ListConfigurable 

type ListConfigurable interface {
	Configurable
	GetListConfig() ListConfig
	SetListConfig(config ListConfig) tea.Cmd
}

ListConfigurable extends Configurable for List components.

type ListContentConfig 

type ListContentConfig struct {
	Enabled   bool
	Formatter ItemFormatter[any]
	Style     lipgloss.Style
	WrapText  bool
	MaxWidth  int

	// Background styling for different states
	CursorBackground   lipgloss.Style // Background when this item has cursor
	SelectedBackground lipgloss.Style // Background when this item is selected
	NormalBackground   lipgloss.Style // Background for normal items
	ApplyCursorBg      bool           // Apply cursor background
	ApplySelectedBg    bool           // Apply selected background
	ApplyNormalBg      bool           // Apply normal background
}

ListContentConfig configures the main content component.

type ListCursorConfig 

type ListCursorConfig struct {
	Enabled         bool
	CursorIndicator string
	NormalSpacing   string
	Style           lipgloss.Style
	Alignment       ListEnumeratorAlignment
	MaxWidth        int

	// Background styling for different states
	CursorBackground   lipgloss.Style // Background when this item has cursor
	SelectedBackground lipgloss.Style // Background when this item is selected
	NormalBackground   lipgloss.Style // Background for normal items
	ApplyCursorBg      bool           // Apply cursor background
	ApplySelectedBg    bool           // Apply selected background
	ApplyNormalBg      bool           // Apply normal background
}

ListCursorConfig configures the cursor component.

type ListEnumerator 

type ListEnumerator func(item Data[any], index int, ctx RenderContext) string

ListEnumerator is a function type that generates a prefix for a list item, such as a bullet point, number, or checkbox.

type ListEnumeratorAlignment 

type ListEnumeratorAlignment int

ListEnumeratorAlignment defines the text alignment for enumerators. 

const (
	ListAlignmentNone ListEnumeratorAlignment = iota
	ListAlignmentLeft
	ListAlignmentRight
)

Constants for list enumerator alignment.

type ListEnumeratorConfig 

type ListEnumeratorConfig struct {
	Enabled    bool
	Enumerator ListEnumerator
	Style      lipgloss.Style
	Alignment  ListEnumeratorAlignment
	MaxWidth   int

	// Background styling for different states
	CursorBackground   lipgloss.Style // Background when this item has cursor
	SelectedBackground lipgloss.Style // Background when this item is selected
	NormalBackground   lipgloss.Style // Background for normal items
	ApplyCursorBg      bool           // Apply cursor background
	ApplySelectedBg    bool           // Apply selected background
	ApplyNormalBg      bool           // Apply normal background
}

ListEnumeratorConfig configures the enumerator component.

type ListModel 

type ListModel interface {
	TeaModel

	// SetFormatter sets a custom item formatter and returns a command.
	SetFormatter(formatter ItemFormatter[any]) tea.Cmd
	// SetAnimatedFormatter sets a custom animated item formatter and returns a command.
	SetAnimatedFormatter(formatter ItemFormatterAnimated[any]) tea.Cmd
	// SetMaxWidth sets the maximum width of the list and returns a command.
	SetMaxWidth(width int) tea.Cmd
	// GetCurrentItem returns the data item currently under the cursor.
	GetCurrentItem() (Data[any], bool)
}

ListModel extends TeaModel with methods specific to the List component.

type ListRenderComponent 

type ListRenderComponent interface {
	// Render generates the string content for this component.
	Render(ctx ListComponentContext) string
	// GetType returns the component's unique type identifier.
	GetType() ListComponentType
	// IsEnabled returns whether this component should be rendered.
	IsEnabled() bool
	// SetEnabled enables or disables this component.
	SetEnabled(enabled bool)
}

ListRenderComponent represents a single, pluggable piece of the list item rendering pipeline, such as the cursor indicator or the item content.

type ListRenderConfig 

type ListRenderConfig struct {
	// ComponentOrder defines the sequence of components to render for each list
	// item (e.g., cursor, enumerator, content).
	ComponentOrder []ListComponentType

	// Component configurations
	CursorConfig      ListCursorConfig
	PreSpacingConfig  ListSpacingConfig
	EnumeratorConfig  ListEnumeratorConfig
	ContentConfig     ListContentConfig
	PostSpacingConfig ListSpacingConfig
	BackgroundConfig  ListBackgroundConfig
}

ListRenderConfig contains the configuration for the component-based list rendering pipeline. It defines which visual components are rendered and in what order.

type ListSpacingConfig 

type ListSpacingConfig struct {
	Enabled bool
	Spacing string
	Style   lipgloss.Style

	// Background styling for different states
	CursorBackground   lipgloss.Style // Background when this item has cursor
	SelectedBackground lipgloss.Style // Background when this item is selected
	NormalBackground   lipgloss.Style // Background for normal items
	ApplyCursorBg      bool           // Apply cursor background
	ApplySelectedBg    bool           // Apply selected background
	ApplyNormalBg      bool           // Apply normal background
}

ListSpacingConfig configures spacing components.

type LoadingFormatterSetMsg deprecated 

type LoadingFormatterSetMsg struct {
	Formatter LoadingRowFormatter
}

LoadingFormatterSetMsg is a message to set a custom loading row formatter.

Deprecated: Use RowFormatterSetMsg instead.

type LoadingRowFormatter 

type LoadingRowFormatter func(
	index int,
	columns []TableColumn,
	ctx RenderContext,
	isCursor bool,
) string

LoadingRowFormatter is a function that defines how a placeholder row is rendered while data is being loaded.

type MaxWidthSetMsg 

type MaxWidthSetMsg struct {
	Width int
}

MaxWidthSetMsg is a message to set the maximum width for a list component.

type Measurer 

type Measurer interface {
	// Measure returns the width and height of the given text.
	Measure(text string) (width int, height int)
}

Measurer provides a method for measuring text dimensions.

type MetadataKey 

type MetadataKey[T any] struct {
	// Key is the string identifier for the metadata.
	Key string
	// DefaultValue is the value returned if the key is not found.
	DefaultValue T
	// Validator is a function to validate values before they are set.
	Validator func(T) error
}

MetadataKey represents a type-safe key for storing and retrieving values from TypedMetadata. It includes a default value and an optional validator function.

type MetadataManager 

type MetadataManager interface {
	// Set stores a value with its associated key.
	Set(key string, value any) error
	// Get retrieves a value by its key.
	Get(key string) (any, bool)
	// Delete removes a key-value pair.
	Delete(key string)
	// Clear removes all key-value pairs.
	Clear()

	// GetRaw returns the raw, untyped metadata map.
	GetRaw() map[string]any
	// SetRaw sets a raw key-value pair.
	SetRaw(key string, value any)
	// Copy creates a deep copy of the metadata manager.
	Copy() MetadataManager
}

MetadataManager provides a type-safe way to manage metadata. 

type NavigationKeyMap struct {
	Up        []string
	Down      []string
	PageUp    []string
	PageDown  []string
	Home      []string
	End       []string
	Select    []string
	SelectAll []string
	Filter    []string
	Sort      []string
	Quit      []string
}

NavigationKeyMap defines the key mappings for component navigation and actions.

func DefaultNavigationKeyMap 

func DefaultNavigationKeyMap() NavigationKeyMap

DefaultNavigationKeyMap returns the default key mappings for navigation.

type NextColumnMsg 

type NextColumnMsg struct{}

NextColumnMsg is a message sent to move to the next column for horizontal navigation/scrolling focus.

type PaddingConfig 

type PaddingConfig struct {
	Left   int
	Right  int
	Top    int
	Bottom int
}

PaddingConfig defines the padding for each side of a cell.

type PageDownMsg 

type PageDownMsg struct{}

PageDownMsg is a message sent to move the cursor down by one page/viewport height.

type PageLeftMsg 

type PageLeftMsg struct{}

PageLeftMsg is a message sent to move the cursor left by one page/viewport width.

type PageRightMsg 

type PageRightMsg struct{}

PageRightMsg is a message sent to move the cursor right by one page/viewport width.

type PageUpMsg 

type PageUpMsg struct{}

PageUpMsg is a message sent to move the cursor up by one page/viewport height.

type PerformanceConfigMsg 

type PerformanceConfigMsg struct {
	Enabled           bool
	MonitorMemory     bool
	MonitorRenderTime bool
	ReportInterval    time.Duration
}

PerformanceConfigMsg is a message to configure performance monitoring.

type PerformanceMonitor 

type PerformanceMonitor interface {
	// GetRenderTime returns the time taken for the last render cycle.
	GetRenderTime() time.Duration
	// GetUpdateTime returns the time taken for the last update cycle.
	GetUpdateTime() time.Duration
	// GetMemoryUsage returns the current memory usage in bytes.
	GetMemoryUsage() uint64

	// StartMonitoring begins tracking performance metrics.
	StartMonitoring()
	// StopMonitoring stops tracking performance metrics.
	StopMonitoring()
	// IsMonitoring returns true if the monitor is currently active.
	IsMonitoring() bool

	// GetReport returns a summary of performance metrics over a period.
	GetReport() PerformanceReport
	// ResetMetrics resets all tracked metrics to zero.
	ResetMetrics()
}

PerformanceMonitor defines the contract for tracking performance metrics.

type PerformanceReport 

type PerformanceReport struct {
	AverageRenderTime time.Duration
	AverageUpdateTime time.Duration
	PeakMemoryUsage   uint64
	TotalOperations   int64
	Uptime            time.Duration
}

PerformanceReport contains a summary of performance metrics.

type PrevColumnMsg 

type PrevColumnMsg struct{}

PrevColumnMsg is a message sent to move to the previous column for horizontal navigation/scrolling focus.

type RealTimeConfigMsg 

type RealTimeConfigMsg struct {
	Enabled  bool
	Interval time.Duration
}

RealTimeConfigMsg is a message to configure real-time update behavior.

type RealTimeUpdateMsg 

type RealTimeUpdateMsg struct{}

RealTimeUpdateMsg is a message to trigger a real-time update of the component.

type RefreshTrigger 

type RefreshTrigger struct {
	// Type is the kind of trigger.
	Type TriggerType
	// Interval is the duration for timer-based triggers.
	Interval time.Duration
	// Event is the name for event-based triggers.
	Event string
	// Condition is the function for conditional triggers.
	Condition func() bool
}

RefreshTrigger defines a condition that, when met, causes an item to be re-rendered. This is essential for animations and real-time updates.

type RenderContext 

type RenderContext struct {
	// MaxWidth is the maximum width available for rendering.
	MaxWidth int
	// MaxHeight is the maximum height available for rendering.
	MaxHeight int

	// Component context
	ColumnIndex int

	// Styling & theming
	// Theme provides the active theme for table components.
	Theme *Theme
	// BaseStyle is the default style for list components.
	BaseStyle lipgloss.Style

	// Terminal capabilities
	// ColorSupport is true if the terminal supports colors.
	ColorSupport bool
	// UnicodeSupport is true if the terminal supports unicode characters.
	UnicodeSupport bool

	// Accessibility
	// HighContrast is true if high contrast mode is enabled.
	HighContrast bool
	// ReducedMotion is true if reduced motion mode is enabled.
	ReducedMotion bool
	// ScreenReader is true if screen reader support is enabled.
	ScreenReader bool

	// Global state
	// CurrentTime is the time of the current render cycle.
	CurrentTime time.Time
	// FocusState contains information about the component's focus.
	FocusState FocusState
	// DeltaTime is the duration since the last render, useful for animations.
	DeltaTime time.Duration

	// State indicators (configurable)
	// ErrorIndicator is the string used to indicate an error state.
	ErrorIndicator string
	// LoadingIndicator is the string used to indicate a loading state.
	LoadingIndicator string
	// DisabledIndicator is the string used to indicate a disabled state.
	DisabledIndicator string
	// SelectedIndicator is the string used to indicate a selected state.
	SelectedIndicator string

	// Utility functions
	// Truncate shortens a string to a given width.
	Truncate func(string, int) string
	// Wrap wraps a string to a given width.
	Wrap func(string, int) []string
	// Measure calculates the width and height of a string.
	Measure func(string, int) (int, int)

	// Error handling
	// OnError is a callback for reporting rendering errors.
	OnError func(error)
}

RenderContext provides dimensional constraints, styling, and utility functions to formatters, ensuring consistent rendering across the component.

type RenderResult 

type RenderResult struct {
	// Content is the rendered string output.
	Content string

	// RefreshTriggers specify conditions under which this content should be
	// re-rendered.
	RefreshTriggers []RefreshTrigger

	// AnimationState stores state between renders for this specific item.
	AnimationState map[string]any

	// Error contains any error that occurred during rendering.
	Error error

	// Fallback content to use if a rendering error occurs.
	Fallback string
}

RenderResult contains the output of an animated rendering operation. It includes the content and metadata needed for re-rendering and state management.

type ResetMsg 

type ResetMsg struct{}

ResetMsg is a message to reset a component to its initial state.

type RowAnimation 

type RowAnimation struct {
	// RowID is the ID of the row to animate.
	RowID string
	// AnimationType is the type of animation.
	AnimationType string
	// State holds the animation's current values.
	State map[string]any
	// Triggers define when the animation should update.
	Triggers []RefreshTrigger
}

RowAnimation represents an animation for an entire table row.

type RowAnimationStartMsg 

type RowAnimationStartMsg struct {
	RowID     string
	Animation RowAnimation
}

RowAnimationStartMsg is a message to start an animation for a specific table row.

type RowAnimationStopMsg 

type RowAnimationStopMsg struct {
	RowID string
}

RowAnimationStopMsg is a message to stop an animation for a specific table row.

type RowFormatter 

type RowFormatter func(
	row TableRow,
	columns []TableColumn,
	cellResults []CellRenderResult,
	ctx RenderContext,
	isCursor bool,
	isSelected bool,
) string

RowFormatter is a function that defines how an entire table row is rendered from its constituent cell results. This allows for custom row-level styling or layout.

type RowFormatterSetMsg 

type RowFormatterSetMsg struct {
	Formatter LoadingRowFormatter
}

RowFormatterSetMsg is a message to set a custom formatter for loading placeholder rows.

type SearchClearMsg 

type SearchClearMsg struct{}

SearchClearMsg is a message to clear the current search query and results.

type SearchResultMsg 

type SearchResultMsg struct {
	Results []int // Indices of matching items
	Query   string
	Total   int
}

SearchResultMsg is a message containing the results of a search operation.

type SearchSetMsg 

type SearchSetMsg struct {
	Query string
	Field string // Optional: search within a specific field
}

SearchSetMsg is a message to initiate a search with a given query.

type SearchableDataSource 

type SearchableDataSource[T any] interface {
	DataSource[T]

	// FindItemIndex searches for an item based on a key-value pair and returns a
	// tea.Cmd that resolves to a message containing the index of the found item.
	FindItemIndex(key string, value any) tea.Cmd
}

SearchableDataSource extends the DataSource interface with search capabilities.

type SelectAllMsg 

type SelectAllMsg struct{}

SelectAllMsg is a message to select all items in the dataset.

type SelectClearMsg 

type SelectClearMsg struct{}

SelectClearMsg is a message to clear all current selections.

type SelectCurrentMsg 

type SelectCurrentMsg struct{}

SelectCurrentMsg is a message to select or toggle the item at the current cursor position.

type SelectRangeMsg 

type SelectRangeMsg struct {
	StartID string
	EndID   string
}

SelectRangeMsg is a message to select a range of items between two item IDs.

type SelectToggleMsg 

type SelectToggleMsg struct {
	Index int
}

SelectToggleMsg is a message to toggle the selection state of an item at a specific index.

type SelectionChangedMsg 

type SelectionChangedMsg struct {
	SelectedIndices []int
	SelectedIDs     []string
	TotalSelected   int
}

SelectionChangedMsg is a message indicating that the selection state has changed within the data source.

type SelectionManager 

type SelectionManager interface {
	// IsSelected checks if an item with the given ID is selected.
	IsSelected(id string) bool
	// GetSelectedIDs returns a slice of IDs for all selected items.
	GetSelectedIDs() []string
	// GetSelectedIndices returns a slice of indices for all selected items.
	GetSelectedIndices() []int
	// GetSelectionCount returns the total number of selected items.
	GetSelectionCount() int

	// Select marks an item as selected.
	Select(id string) bool
	// Deselect removes an item from the selection.
	Deselect(id string) bool
	// Toggle flips the selection state of an item.
	Toggle(id string) bool
	// SelectAll marks all given IDs as selected.
	SelectAll(ids []string) bool
	// ClearSelection removes all selections.
	ClearSelection()
	// SelectRange selects all items between a start and end ID.
	SelectRange(startID, endID string) bool

	// GetSelectionMode returns the current selection mode.
	GetSelectionMode() SelectionMode
	// SetSelectionMode sets the selection mode.
	SetSelectionMode(mode SelectionMode)
}

SelectionManager defines the contract for managing item selections.

type SelectionMode 

type SelectionMode int

SelectionMode defines the selection behavior of a component. 

const (
	// SelectionSingle allows only one item to be selected at a time.
	SelectionSingle SelectionMode = iota
	// SelectionMultiple allows multiple items to be selected simultaneously.
	SelectionMultiple
	// SelectionNone disables item selection entirely.
	SelectionNone
)

type SelectionModeSetMsg 

type SelectionModeSetMsg struct {
	Mode SelectionMode
}

SelectionModeSetMsg is a message to change the component's selection mode (e.g., single, multiple, none).

type SelectionResponseMsg 

type SelectionResponseMsg struct {
	Success     bool
	Index       int
	ID          string
	Selected    bool
	Operation   string // e.g., "toggle", "selectAll", "clear"
	Error       error
	AffectedIDs []string // For operations that affect multiple items
}

SelectionResponseMsg is a message from a DataSource indicating the result of a selection operation.

type SetComponentBackgroundMsg 

type SetComponentBackgroundMsg struct {
	ComponentType ListComponentType
	CursorBg      lipgloss.Style
	SelectedBg    lipgloss.Style
	NormalBg      lipgloss.Style
	ApplyCursor   bool
	ApplySelected bool
	ApplyNormal   bool
}

SetComponentBackgroundMsg is a message to configure background styling for a specific component

type SetCursorRowStylingMsg 

type SetCursorRowStylingMsg struct {
	Enabled    bool
	Background lipgloss.Style
}

SetCursorRowStylingMsg is a message to enable/disable full row cursor background styling

type SetFullRowSelectionMsg 

type SetFullRowSelectionMsg struct {
	Enabled    bool
	Background lipgloss.Style
}

SetFullRowSelectionMsg is a message to enable/disable full row selection background styling

type SimpleCellFormatter 

type SimpleCellFormatter func(
	cellValue string,
	rowIndex int,
	column TableColumn,
	ctx RenderContext,
	isCursor bool,
	isSelected bool,
	isActiveCell bool,
) string

SimpleCellFormatter is a function that defines how a table cell's content is rendered. It is "simple" because it receives the final cell value and does not need to handle complex data structures; the table component manages data extraction. It automatically handles text truncation based on column width.

type SimpleHeaderFormatter 

type SimpleHeaderFormatter func(
	column TableColumn,
	ctx RenderContext,
) string

SimpleHeaderFormatter is a function that defines how a table header cell is rendered. It automatically handles text truncation based on column width.

type SortAddMsg 

type SortAddMsg struct {
	Field     string
	Direction string
}

SortAddMsg is a message to add a field to a multi-column sort configuration.

type SortRemoveMsg 

type SortRemoveMsg struct {
	Field string
}

SortRemoveMsg is a message to remove a field from the sorting configuration.

type SortSetMsg 

type SortSetMsg struct {
	Field     string
	Direction string // "asc" or "desc"
}

SortSetMsg is a message to set the sorting for a specific field and direction.

type SortToggleMsg 

type SortToggleMsg struct {
	Field string
}

SortToggleMsg is a message to toggle the sort order of a field (e.g., asc -> desc -> none).

type SortsClearAllMsg 

type SortsClearAllMsg struct{}

SortsClearAllMsg is a message to clear all sorting configurations.

type StatusMsg 

type StatusMsg struct {
	Message string
	Type    StatusType
}

StatusMsg is a message used to display status information to the user.

type StatusType 

type StatusType int

StatusType defines the category of a status message. 

const (
	StatusInfo StatusType = iota
	StatusWarning
	StatusError
	StatusSuccess
)

Constants for different status message types.

type StyleConfig 

type StyleConfig struct {
	// CursorStyle is the style for the item under the cursor.
	CursorStyle lipgloss.Style
	// SelectedStyle is the style for a selected item.
	SelectedStyle lipgloss.Style
	// DefaultStyle is the style for a normal, unselected item.
	DefaultStyle lipgloss.Style
	// ThresholdStyle is the style for items at the scroll threshold.
	ThresholdStyle lipgloss.Style
	// DisabledStyle is the style for a disabled item.
	DisabledStyle lipgloss.Style
	// LoadingStyle is the style for a loading item.
	LoadingStyle lipgloss.Style
	// ErrorStyle is the style for an item with an error.
	ErrorStyle lipgloss.Style
}

StyleConfig defines the styles for various states of list items.

type StyleConfigSetMsg 

type StyleConfigSetMsg struct {
	Config StyleConfig
}

StyleConfigSetMsg is a message to apply a new style configuration to a list component.

type TableColumn 

type TableColumn struct {
	// Title is the column header text.
	Title string

	// Width is the column width in characters.
	Width int

	// Alignment defines how text is aligned in the column cells (left, right,
	// center). Use the AlignLeft, AlignCenter, or AlignRight constants.
	Alignment int

	// Field is the identifier used for sorting/filtering operations. This should
	// correspond to a key in the underlying data source.
	Field string

	// HeaderAlignment defines alignment for the header text, which can be
	// different from the cell alignment.
	HeaderAlignment int
	// HeaderConstraint defines formatting constraints for the header cell.
	HeaderConstraint CellConstraint
}

TableColumn represents the configuration for a single column in a table. It defines properties like the title, width, alignment, and the data field it corresponds to.

type TableConfig 

type TableConfig struct {
	// Columns defines the structure of the table columns.
	Columns []TableColumn
	// ShowHeader controls the visibility of the table header.
	ShowHeader bool
	// ShowBorders is a global toggle for all table borders.
	ShowBorders bool

	// Granular border configuration
	// ShowTopBorder controls the visibility of the top border.
	ShowTopBorder bool
	// ShowBottomBorder controls the visibility of the bottom border.
	ShowBottomBorder bool
	// ShowHeaderSeparator controls the visibility of the line between the header
	// and the body.
	ShowHeaderSeparator bool

	// Space removal for borders (when true, completely removes the line space)
	// RemoveTopBorderSpace, if true, removes the line where the top border would be.
	RemoveTopBorderSpace bool
	// RemoveBottomBorderSpace, if true, removes the line where the bottom border would be.
	RemoveBottomBorderSpace bool

	// FullRowHighlighting enables a mode where the entire row is highlighted by the cursor.
	FullRowHighlighting bool

	// ResetScrollOnNavigation, if true, resets horizontal scroll offsets when
	// navigating between rows.
	ResetScrollOnNavigation bool

	// ActiveCellIndicationEnabled toggles the background highlighting of the active cell.
	ActiveCellIndicationEnabled bool
	// ActiveCellBackgroundColor sets the background color for the active cell.
	ActiveCellBackgroundColor string

	// ViewportConfig defines the viewport behavior.
	ViewportConfig ViewportConfig

	// Theme defines the visual style of the table.
	Theme Theme

	// SelectionMode defines the selection behavior.
	SelectionMode SelectionMode

	// KeyMap defines the keybindings for navigation and actions.
	KeyMap NavigationKeyMap
}

TableConfig contains all configuration options for a table component.

type TableConfigValidator 

type TableConfigValidator interface {
	Validator
	ValidateTableConfig(config *TableConfig) error
	FixTableConfig(config *TableConfig) error
}

TableConfigValidator validates TableConfig structs.

type TableConfigurable 

type TableConfigurable interface {
	Configurable
	GetTableConfig() TableConfig
	SetTableConfig(config TableConfig) tea.Cmd
}

TableConfigurable extends Configurable for Table components.

type TableModel 

type TableModel interface {
	TeaModel

	// SetColumns sets the table's column configuration and returns a command.
	SetColumns(columns []TableColumn) tea.Cmd
	// SetHeaderVisibility sets the visibility of the table header and returns a command.
	SetHeaderVisibility(visible bool) tea.Cmd
	// SetBorderVisibility sets the visibility of table borders and returns a command.
	SetBorderVisibility(visible bool) tea.Cmd
	// SetCellFormatter sets a custom formatter for a specific column and returns a command.
	SetCellFormatter(columnIndex int, formatter CellFormatter) tea.Cmd
	// SetCellAnimatedFormatter sets a custom animated formatter for a specific column and returns a command.
	SetCellAnimatedFormatter(columnIndex int, formatter CellFormatterAnimated) tea.Cmd
	// SetRowFormatter sets a custom row formatter and returns a command.
	SetRowFormatter(formatter RowFormatter) tea.Cmd
	// SetHeaderFormatter sets a custom header formatter and returns a command.
	SetHeaderFormatter(formatter HeaderFormatter) tea.Cmd
	// SetColumnConstraints sets layout constraints for a specific column and returns a command.
	SetColumnConstraints(columnIndex int, constraints CellConstraint) tea.Cmd
	// GetCurrentRow returns the data for the row currently under the cursor.
	GetCurrentRow() (TableRow, bool)
}

TableModel extends TeaModel with methods specific to the Table component.

type TableRow 

type TableRow struct {
	// ID is a stable unique identifier for this row. It is crucial for
	// maintaining state across data refreshes and for operations like selection
	// and animation.
	ID string

	// Cells contains the string values for each column in the row. The order of
	// cells should correspond to the order of columns defined in the table
	// configuration.
	Cells []string
}

TableRow represents a row of data in the table. It contains a stable unique identifier and the cell data for that row.

type TableThemeSetMsg 

type TableThemeSetMsg struct {
	Theme Theme
}

TableThemeSetMsg is a message to apply a new theme to a table component.

type TeaModel 

type TeaModel interface {
	tea.Model

	// Focus sets the component to a focused state, allowing it to receive
	// keyboard input.
	Focus() tea.Cmd
	// Blur removes focus from the component.
	Blur()
	// IsFocused returns true if the component currently has focus.
	IsFocused() bool

	// State access
	// GetState returns the current viewport state of the component.
	GetState() ViewportState
	// GetTotalItems returns the total number of items in the dataset.
	GetTotalItems() int

	// Selection
	// GetSelectedIndices returns the indices of all selected items.
	GetSelectedIndices() []int
	// GetSelectedIDs returns the stable IDs of all selected items.
	GetSelectedIDs() []string
	// GetSelectionCount returns the total number of selected items.
	GetSelectionCount() int
}

TeaModel is the core interface that all vtable components (List, Table, etc.) implement. It extends the standard bubbletea.Model with common functionality for focus management, state access, and selection.

type TextProcessor 

type TextProcessor interface {
	Truncator
	Wrapper
	Measurer
}

TextProcessor combines the Truncator, Wrapper, and Measurer interfaces.

type Theme 

type Theme struct {
	// HeaderStyle is the style for header cells.
	HeaderStyle lipgloss.Style
	// CellStyle is the style for non-header cells.
	CellStyle lipgloss.Style
	// CursorStyle is the style for the cell under the cursor.
	CursorStyle lipgloss.Style
	// SelectedStyle is the style for selected rows.
	SelectedStyle lipgloss.Style
	// FullRowCursorStyle is the style applied to the entire row when full-row
	// highlighting is enabled.
	FullRowCursorStyle lipgloss.Style
	// BorderChars defines the characters used for drawing table borders.
	BorderChars BorderChars
	// BorderColor is the color for table borders.
	BorderColor string
	// HeaderColor is the color for header text.
	HeaderColor string
	// AlternateRowStyle is a style applied to alternating rows for readability.
	AlternateRowStyle lipgloss.Style
	// DisabledStyle is the style for disabled rows.
	DisabledStyle lipgloss.Style
	// LoadingStyle is the style for loading placeholder rows.
	LoadingStyle lipgloss.Style
	// ErrorStyle is the style for rows with errors.
	ErrorStyle lipgloss.Style
}

Theme defines the visual appearance and character set for table components.

type ThemeProvider 

type ThemeProvider interface {
	// GetTheme returns the currently active theme.
	GetTheme() Theme
	// SetTheme sets a new theme and returns a command.
	SetTheme(theme Theme) tea.Cmd

	// GetStyleConfig returns the currently active style configuration.
	GetStyleConfig() StyleConfig
	// SetStyleConfig sets a new style configuration and returns a command.
	SetStyleConfig(config StyleConfig) tea.Cmd

	// ApplyTheme applies a named style from the theme to the given content.
	ApplyTheme(content string, style string) string
	// GetBorderChars returns the character set used for borders.
	GetBorderChars() BorderChars
	// SetBorderChars sets a new character set for borders and returns a command.
	SetBorderChars(chars BorderChars) tea.Cmd
}

ThemeProvider defines the contract for managing themes and styles.

type ThemeSetMsg 

type ThemeSetMsg struct {
	Theme interface{} // Can be Theme or StyleConfig
}

ThemeSetMsg is a message to apply a new theme or style configuration to a component.

type TopBorderSpaceRemovalMsg 

type TopBorderSpaceRemovalMsg struct {
	Remove bool
}

TopBorderSpaceRemovalMsg is a message to control whether the space for the top border is completely removed when it's not visible.

type TopBorderVisibilityMsg 

type TopBorderVisibilityMsg struct {
	Visible bool
}

TopBorderVisibilityMsg is a message to set the visibility of the table's top border.

type TreeJumpToIndexMsg 

type TreeJumpToIndexMsg struct {
	Index         int
	ExpandParents bool // If true, expand all parent nodes to make the target item visible
}

TreeJumpToIndexMsg is a message sent to move the cursor to a specific index in a tree component, with an option to expand parent nodes to make the target visible.

type TriggerType 

type TriggerType int

TriggerType defines the different kinds of animation triggers. 

const (
	// TriggerTimer updates the animation periodically.
	TriggerTimer TriggerType = iota
	// TriggerEvent updates the animation in response to a specific event.
	TriggerEvent
	// TriggerConditional updates the animation when a specific condition is met.
	TriggerConditional
)

type Truncator 

type Truncator interface {
	// Truncate shortens the given text to the specified maximum width.
	Truncate(text string, maxWidth int) string
}

Truncator provides a method for truncating text.

type TypedMetadata 

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

TypedMetadata provides a type-safe container for custom metadata. It uses MetadataKey to ensure type correctness at compile time.

func NewTypedMetadata 

func NewTypedMetadata() TypedMetadata

NewTypedMetadata creates a new, empty TypedMetadata instance.

func (*TypedMetadata) GetRaw 

func (tm *TypedMetadata) GetRaw() map[string]any

GetRaw returns the raw map[string]any for situations where type safety is not required, such as during serialization.

func (*TypedMetadata) SetRaw 

func (tm *TypedMetadata) SetRaw(key string, value any)

SetRaw sets a value without type-safety. Use with caution.

type ValidationErrorMsg 

type ValidationErrorMsg struct {
	Field   string
	Value   any
	Error   error
	Context string
}

ValidationErrorMsg is a message representing a validation error for a specific field.

type Validator 

type Validator interface {
	// Validate checks if the configuration is valid and returns an error if not.
	Validate() error

	// Fix attempts to correct common configuration issues.
	Fix() error
}

Validator provides methods for validating and fixing configuration structs.

type ViewportConfig 

type ViewportConfig struct {
	// Height is the number of items visible in the viewport.
	Height int

	// TopThreshold is the offset from the viewport's start where scrolling up is
	// triggered. A value of -1 disables it.
	TopThreshold int

	// BottomThreshold is the offset from the viewport's end where scrolling down
	// is triggered. A value of -1 disables it.
	BottomThreshold int

	// ChunkSize is the number of items to load in each data chunk.
	ChunkSize int

	// InitialIndex is the starting cursor position when the component is
	// initialized.
	InitialIndex int

	// BoundingAreaBefore is the number of items to keep loaded before the
	// viewport top.
	BoundingAreaBefore int

	// BoundingAreaAfter is the number of items to keep loaded after the viewport
	// bottom.
	BoundingAreaAfter int
}

ViewportConfig defines the configuration for the viewport's behavior, including its size, scrolling thresholds, and data chunking strategy.

type ViewportConfigMsg 

type ViewportConfigMsg struct {
	Config ViewportConfig
}

ViewportConfigMsg is a message to apply a new ViewportConfig.

type ViewportConfigValidator 

type ViewportConfigValidator interface {
	Validator
	ValidateViewportConfig(config *ViewportConfig) error
	FixViewportConfig(config *ViewportConfig) error
}

ViewportConfigValidator validates ViewportConfig structs.

type ViewportResizeMsg 

type ViewportResizeMsg struct {
	Width  int
	Height int
}

ViewportResizeMsg is a message indicating that the component's available size has changed.

type ViewportState 

type ViewportState struct {
	// ViewportStartIndex is the absolute index of the first item visible in the
	// viewport.
	ViewportStartIndex int

	// CursorIndex is the absolute index of the selected item in the entire
	// dataset.
	CursorIndex int

	// CursorViewportIndex is the relative index of the cursor within the visible
	// viewport (0 to Height-1).
	CursorViewportIndex int

	// IsAtTopThreshold indicates if the cursor is at the top scroll-triggering
	// threshold.
	IsAtTopThreshold bool

	// IsAtBottomThreshold indicates if the cursor is at the bottom
	// scroll-triggering threshold.
	IsAtBottomThreshold bool

	// AtDatasetStart indicates if the viewport is at the very beginning of the
	// dataset.
	AtDatasetStart bool

	// AtDatasetEnd indicates if the viewport is at the very end of the dataset.
	AtDatasetEnd bool
}

ViewportState contains the current positional information of a component's viewport, such as cursor position and scroll offsets.

type Wrapper 

type Wrapper interface {
	// Wrap breaks the given text into multiple lines, each no wider than the
	// specified maximum width.
	Wrap(text string, maxWidth int) []string
}

Wrapper provides a method for wrapping text.

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.