charmbracelet/x

Pony uses a pattern where stateful components manage their own state and logic but render to stateless pony.Element structures. This allows components to be decoupled from layout concerns, as the pony layout engine handles sizing automatically.

The Pattern

1. Component manages state: The component handles Update logic and stores internal data.
2. Component renders to Element: The component's Render method returns a declarative pony.Element (not a string or a view).
3. Slots inject components: Templates use <slot name="..." /> placeholders to define where components should be injected.
4. Bubble Tea routes events: The main Bubble Tea Update loop routes incoming messages to the currently focused component.

Key Insight

Components do not need to know their own size. They return Element structures, and pony's layout engine calculates the necessary dimensions during the template rendering phase.

type Input struct {
    value   string
    cursor  int
    focused bool
}

// Update handles events (state management)
func (i *Input) Update(msg tea.Msg) {
    switch msg := msg.(type) {
    case tea.KeyPressMsg:
        i.value += msg.String()
        i.cursor++
    }
}

// Render returns pony Element (no size needed!)
func (i *Input) Render() pony.Element {
    style, _ := pony.ParseStyle("fg:white")
    
    return pony.NewBox(
        pony.NewText(i.value).WithStyle(style),
    ).WithBorder("rounded").WithPadding(1)
}

Pony provides stateless mouse click handling using RenderWithBounds and HitTest. This allows you to capture clicks without mutating your model inside the View() function.

To implement this:

1. Use tmpl.RenderWithBounds to get both the rendered screen and a BoundsMap.
2. Set view.MouseMode = tea.MouseModeAllMotion in your Bubble Tea view.
3. Use view.Callback to perform a HitTest on the mouse coordinates.
4. Return a tea.Cmd containing the element's ID to be handled in your Update() function.

Important: To ensure clicks on a custom component return the component's ID rather than its children's IDs, you must call SetID() on the root element returned by the component's Render() method.

type buttonClickMsg string

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case buttonClickMsg:
        switch msg {
        case "submit-btn":
            return m, m.submitForm()
        case "cancel-btn":
            return m, tea.Quit
        }
    }
    return m, nil
}

func (m model) View() tea.View {
    data := ViewData{...}

    // Render and get bounds map
    scr, boundsMap := m.template.RenderWithBounds(data, nil, m.width, m.height)

    view := tea.NewView(scr.Render())
    view.MouseMode = tea.MouseModeAllMotion

    view.Callback = func(msg tea.Msg) tea.Cmd {
        if click, ok := msg.(tea.MouseClickMsg); ok {
            mouse := click.Mouse()

            if elem := boundsMap.HitTest(mouse.X, mouse.Y); elem != nil {
                return func() tea.Msg {
                    return buttonClickMsg(elem.ID())
                }
            }
        }
        return nil
    }

    return view
}

To use pony with Bubble Tea, use pony for declarative view rendering while delegating application lifecycle, event handling, and commands to Bubble Tea.

Follow these integration steps:

1. Store the Template in your Model: Parse your markup during model initialization using pony.MustParse(markup).
2. Render in the View() method: Prepare your data in a map[string]interface{} and call m.template.RenderToSize(data, m.width, m.height) to generate the output. Wrap the result in tea.NewView(output).
3. Handle Window Resizing: Capture tea.WindowSizeMsg in your Update method to update the width and height stored in your model, ensuring the next RenderToSize call uses the correct dimensions.
4. Request Initial Size: Return tea.RequestWindowSize from your Init() method to ensure the first render has valid dimensions.

type model struct {
    template *pony.Template
    width    int
    height   int
    count    int
}

func initialModel() model {
    return model{
        template: pony.MustParse(markup),
    }
}

func (m model) View() tea.View {
    data := map[string]interface{}{
        "Count": m.count,
    }
    output := m.template.RenderToSize(data, m.width, m.height)
    return tea.NewView(output)
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        m.width = msg.Width
        m.height = msg.Height
    }
    return m, nil
}

func (m model) Init() tea.Cmd {
    return tea.RequestWindowSize
}

To create a stateful component, implement a struct that manages its own internal state and provides two primary methods:

1. Update(msg tea.Msg): Handles state transitions based on incoming Bubble Tea messages.
2. Render() pony.Element: Returns a declarative pony.Element representing the component's visual structure.

Because components return pony.Element, they can be composed of any pony primitives (like NewBox, NewText, etc.) and benefit from automatic layout management.

type Input struct {
    value   string
    cursor  int
    focused bool
}

func (i *Input) Update(msg tea.Msg) {
    switch msg := msg.(type) {
    case tea.KeyPressMsg:
        i.value += msg.String()
        i.cursor++
    }
}

func (i *Input) Render() pony.Element {
    style, _ := pony.ParseStyle("fg:white")
    
    return pony.NewBox(
        pony.NewText(i.value).WithStyle(style),
    ).WithBorder("rounded").WithPadding(1)
}