app

Documentation

Index

• Constants
• Variables
• func ApplyBorder(s lipgloss.Style, options Border) lipgloss.Style
• func ApplyMargin(s lipgloss.Style, options Margin) lipgloss.Style
• func ApplyPadding(s lipgloss.Style, options Padding) lipgloss.Style
• func New(ctx *Ctx, root FC, options ...AppOption) *app
• func NewUIStateContext() *uiStateContext
• func UseAction(c *Ctx, handler func(childID string))
• func UseCursor(c *Ctx, cursor *tea.Cursor, offsetX int, offsetY int)
• func UseEffect(c *Ctx, effect func(), deps []any)
• func UseEffectWithCleanup(c *Ctx, effect func() func(), deps []any)
• func UseFCs(c *Ctx, fcs FCs) []string
• func UseGlobalKeyHandler(c *Ctx, handler KeyHandler)
• func UseGlobalPosition(c *Ctx) (int, int)
• func UseID(c *Ctx) string
• func UseIsFocused(c *Ctx) bool
• func UseIsHovered(c *Ctx) (bool, string)
• func UseKeyHandler(c *Ctx, handler KeyHandler)
• func UseMouseHandler(c *Ctx, handler MouseHandler)
• func UseMsgHandler(c *Ctx, handler MsgHandler)
• func UseOnFocused(c *Ctx, onFocused func(isReverse bool))
• func UseSize(c *Ctx) (int, int)
• func UseState[T any](c *Ctx, initialValue T) (T, func(valueOrUpdater interface{}))
• func UseTick(c *Ctx, interval time.Duration, callback func())
• func Visit(node *C, index int, ctx *Ctx, visitor VisitorFunc, order Order)
• type AppOption
  • func WithTheme(theme *style.AppTheme) AppOption
• type AppOptions
• type Border
• type C
  • func (c *C) String() string
• type Ctx
  • func NewCtx() *Ctx
  • func (c *Ctx) ExecuteCmd(cmd tea.Cmd)
  • func (c *Ctx) FocusNext() string
  • func (c *Ctx) FocusPrev() string
  • func (c *Ctx) FocusThis(id string)
  • func (c *Ctx) GetContextValue(contextID uint64) (any, bool)
  • func (c *Ctx) MouseZone(content string) string
  • func (c *Ctx) MouseZoneChild(childID string, content string) string
  • func (c *Ctx) PopContextValue(contextID uint64)
  • func (c *Ctx) PushContextValue(contextID uint64, value any)
  • func (ctx *Ctx) Quit()
  • func (c *Ctx) Render(fn func(c *Ctx, props Props) string, props Props) *C
  • func (c *Ctx) RenderWithName(fn func(c *Ctx, props Props) string, props Props, name string) *C
  • func (c *Ctx) Update()
  • func (c *Ctx) UpdateInMs(ms int)
• type FC
• type FCs
• type InvalidateMsg
• type KeyHandler
• type Layout
• type LayoutDirection
• type Margin
• type MouseHandler
• type MsgHandler
• type Order
• type Padding
• type Props
• type TickMsg
• type VisitorFunc

Constants

const (
	LayoutPhaseIntrincintWidth layoutPhase = iota
	LayoutPhaseIntrincintHeight
	LayoutPhaseAbsolutePositions
	LayoutPhaseFinalRender
)

Variables

var RunOnceDeps = []any{}

Functions

func ApplyBorder

func ApplyBorder(s lipgloss.Style, options Border) lipgloss.Style

func ApplyMargin

func ApplyMargin(s lipgloss.Style, options Margin) lipgloss.Style

func ApplyPadding

func ApplyPadding(s lipgloss.Style, options Padding) lipgloss.Style

func New

func New(ctx *Ctx, root FC, options ...AppOption) *app

func NewUIStateContext

func NewUIStateContext() *uiStateContext

func UseAction

func UseAction(c *Ctx, handler func(childID string))

UseAction registers a function to be called when the component is clicked with left mouse button or Enter is pressed while the component is focused.

func UseCursor

func UseCursor(c *Ctx, cursor *tea.Cursor, offsetX int, offsetY int)

UseCursor updates the cursor position based on the component's position The offsets are local only offsets from the top left of the current component.

func UseEffect

func UseEffect(c *Ctx, effect func(), deps []any)

UseEffect is the same as UseEffectWithCleanup but without a cleanup function.

func UseEffectWithCleanup

func UseEffectWithCleanup(c *Ctx, effect func() func(), deps []any)

UseEffect schedules a function to run after render, and optionally clean up. Dependencies (deps) are checked to see if the effect should re-run. If deps is nil, the effect runs after every render. If deps is an empty slice, it runs only once after the initial render and on unmount.

func UseFCs

func UseFCs(c *Ctx, fcs FCs) []string

UseFCs executes the children function to get pre-rendered Components and returns their string contents for layout component consumption

func UseGlobalKeyHandler

func UseGlobalKeyHandler(c *Ctx, handler KeyHandler)

UseGlobalKeyHandler registers a function to handle key presses globally. They are called in reverse order of registration.

func UseGlobalPosition

func UseGlobalPosition(c *Ctx) (int, int)

func UseID

func UseID(c *Ctx) string

Returns the component ID

func UseIsFocused

func UseIsFocused(c *Ctx) bool

Registers component as focusable and returns the focus state

func UseIsHovered

func UseIsHovered(c *Ctx) (bool, string)

Returns the ID of the component that is hovered. If the component is hovered, it returns true and any potential child ID.

func UseKeyHandler

func UseKeyHandler(c *Ctx, handler KeyHandler)

UseKeyHandler registers a function to handle key presses within a component. This handler is only called if the component is focused. The handler function should return true if it handled the key, false otherwise.

func UseMouseHandler

func UseMouseHandler(c *Ctx, handler MouseHandler)

UseMouseHandler registers a function to handle mouse events within a component.

func UseMsgHandler

func UseMsgHandler(c *Ctx, handler MsgHandler)

func UseOnFocused

func UseOnFocused(c *Ctx, onFocused func(isReverse bool))

func UseSize

func UseSize(c *Ctx) (int, int)

func UseState

func UseState[T any](c *Ctx, initialValue T) (T, func(valueOrUpdater interface{}))

UseState provides stateful value and a function to update it. It's analogous to React's useState hook. IMPORTANT: Hooks must be called in the same order on every render, and they must not be called conditionally.

func UseTick

func UseTick(c *Ctx, interval time.Duration, callback func())

UseTick schedules a function to be called at a specified interval. The callback will be invoked in a separate goroutine managed by the tick system.

func Visit

func Visit(node *C, index int, ctx *Ctx, visitor VisitorFunc, order Order)

Types

type AppOption

type AppOption func(*AppOptions)

func WithTheme

func WithTheme(theme *style.AppTheme) AppOption

type AppOptions

type AppOptions struct {
	Theme *style.AppTheme
}

type Border

type Border struct {
	Border       lipgloss.Border
	BorderTop    bool
	BorderBottom bool
	BorderLeft   bool
	BorderRight  bool
	Color        color.Color
}

type C

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

C represents an instance of a functional component (FC). It holds the component's ID, focusable state, function reference, props, event handlers, and state management for both state and effects.

func (*C) String

func (c *C) String() string

type Ctx

type Ctx struct {
	UIState *uiStateContext

	Theme *style.AppTheme

	CurrentBg color.Color
	// Layout
	LayoutPhase layoutPhase

	Cursor *tea.Cursor
	// contains filtered or unexported fields
}

func NewCtx

func NewCtx() *Ctx

func (*Ctx) ExecuteCmd

func (c *Ctx) ExecuteCmd(cmd tea.Cmd)

func (*Ctx) FocusNext

func (c *Ctx) FocusNext() string

func (*Ctx) FocusPrev

func (c *Ctx) FocusPrev() string

func (*Ctx) FocusThis

func (c *Ctx) FocusThis(id string)

FocusThis sets the focus to the component with the given ID. If the component is not focusable, it will try to find a parent that is focusable. If no focusable parent is found, it sets the focused ID to empty.

func (*Ctx) GetContextValue

func (c *Ctx) GetContextValue(contextID uint64) (any, bool)

getContextValue retrieves the current value for a given context ID from the top of its stack.

func (*Ctx) MouseZone

func (c *Ctx) MouseZone(content string) string

MouseZone creates a mouse zone for the given content. The ID of the zone is the components ID.

func (*Ctx) MouseZoneChild

func (c *Ctx) MouseZoneChild(childID string, content string) string

MouseZoneChild creates a mouse zone for child (sub part) of a component. The ID of the zone is the components ID + "###" + childID. MouseHandlers will receive the childID extracted from the ID mentioned above.

func (*Ctx) PopContextValue

func (c *Ctx) PopContextValue(contextID uint64)

popContextValue removes the top value from the stack for a given context ID.

func (*Ctx) PushContextValue

func (c *Ctx) PushContextValue(contextID uint64, value any)

pushContextValue adds a value to the stack for a given context ID.

func (*Ctx) Quit

func (ctx *Ctx) Quit()

Quit signals the application to stop, ensuring cleanup like stopping active timers.

func (*Ctx) Render

func (c *Ctx) Render(fn func(c *Ctx, props Props) string, props Props) *C

Render a functional component with the given props. This function is responsible for managing the lifecycle of the component, including state management, effect handling, and ID management.

func (*Ctx) RenderWithName

func (c *Ctx) RenderWithName(fn func(c *Ctx, props Props) string, props Props, name string) *C

func (*Ctx) Update

func (c *Ctx) Update()

Invalidates the UI and forces a re-render. Requires a tea.Program to be set with app.SetTeaProgram. This is useful for performance optimizations where a tick is too expensive.

func (*Ctx) UpdateInMs

func (c *Ctx) UpdateInMs(ms int)

type FC

type FC = func(c *Ctx) *C

type FCs

type FCs = func(c *Ctx) []*C

FCs is a function that returns a slice of pre-rendered Components. This ensures that all child elements must be created via c.Render while allowing for conditional logic when rendering children.

type InvalidateMsg

type InvalidateMsg struct{}

type KeyHandler

type KeyHandler func(keyMsg tea.KeyMsg) bool

KeyHandler defines the signature for component-internal key handlers. It returns true if the key press was handled, false otherwise.

type Layout

type Layout struct {
	Direction LayoutDirection
	GrowX     bool
	GrowY     bool
	GapX      int
	GapY      int
	Width     int
	Height    int
}

type LayoutDirection

type LayoutDirection int

const (
	Vertical LayoutDirection = iota
	Horizontal
)

type Margin

type Margin struct {
	M  int
	MT int
	MB int
	ML int
	MR int
	MY int
	MX int
}

type MouseHandler

type MouseHandler func(msg tea.MouseMsg, childID string) bool

MouseHandler defines the signature for component-internal mouse handlers.

type MsgHandler

type MsgHandler func(msg tea.Msg) tea.Cmd

MsgHandler is for receiving raw tea.Msg messages.

type Order

type Order int

const (
	PreOrder Order = iota
	PostOrder
)

type Padding

type Padding struct {
	P  int
	PT int
	PB int
	PL int
	PR int
	PY int
	PX int
}

type Props

type Props any

Props is the generic type for component properties

type TickMsg

type TickMsg struct {
	OccurredAt time.Time
}

type VisitorFunc

type VisitorFunc func(node *C, index int, ctx *Ctx)