element.go

package wui

// Element is the renderable unit. Every concrete element type satisfies
// it; renderers type-switch on the concrete type.
type Element interface {
	isElement()
}

// Direction controls Box layout axis.
type Direction int

const (
	Row Direction = iota
	Column
)

// Align values for flex-like alignment.
type Align int

const (
	AlignStart Align = iota
	AlignCenter
	AlignEnd
	AlignStretch
)

type TextEl struct {
	Content string
	Style   Style
}

type BoxEl struct {
	Direction Direction
	Gap       int
	Align     Align // cross-axis placement of children (align-items)
	Children  []Element
	Style     Style

	// Justify distributes children along the Box's main axis
	// (justify-content). It needs a resolved main-axis size to work
	// against — Style.Width for a Row, Style.Height for a Column —
	// and AlignStretch behaves as AlignStart.
	Justify Align

	// Wrap lets a Row collapse: in HTML it is flex-wrap, in the TUI
	// the Row re-lays itself out as a Column when its children do not
	// fit the available width. See Sidebar for the ready-made use.
	Wrap bool
}

type ButtonEl struct {
	ID       string // optional; focus key falls back to the label
	Label    string
	OnClick  func() Msg
	Style    Style
	Disabled bool
}

type TextInputEl struct {
	ID          string
	Value       string
	Placeholder string
	Password    bool
	OnChange    func(string) Msg
	OnSubmit    func(string) Msg
	Style       Style
	Disabled    bool
}

type FormEl struct {
	Children []Element
	OnSubmit func(values map[string]string) Msg
	Style    Style
}

type ListEl struct {
	Items   []Element
	Ordered bool
	Style   Style
}

type ScrollAreaEl struct {
	Child     Element
	MaxHeight int
	Style     Style
}

type CheckboxEl struct {
	ID       string
	Label    string
	Checked  bool
	OnToggle func(checked bool) Msg
	Style    Style
	Disabled bool
}

type CardEl struct {
	Title string
	Child Element
	Style Style
}

type LinkEl struct {
	Label string
	Href  string
	Style Style
}

type TableEl struct {
	Columns []string
	Rows    [][]string
	Style   Style
}

// EmptyEl renders nothing. It is what conditional helpers return for a
// false branch, so callers never have to deal with a nil Element.
type EmptyEl struct{}

// SpacerEl is flexible empty space inside a Box: Size cells/lines of
// blank space, or — when Size is 0 — a stretch that pushes the
// surrounding children apart.
type SpacerEl struct {
	Size int
}

// DividerEl is a horizontal rule.
type DividerEl struct {
	Label string // optional text embedded in the rule
	Style Style
}

// ProgressEl is a determinate progress bar. Value is clamped to 0..1.
type ProgressEl struct {
	Value      float64
	Width      int  // bar width in cells; 0 = default (20)
	ShowLabel  bool // append " 42%"
	Style      Style
	FilledRune string // TUI fill glyph; defaults to "█"
	EmptyRune  string // TUI track glyph; defaults to "░"
}

// SpinnerEl is an indeterminate activity indicator. Frame selects which
// glyph of the animation to draw — the app owns the animation clock, so
// the renderers stay pure. Drive it from a Tick Cmd.
type SpinnerEl struct {
	Frame int
	Label string
	Style Style
}

// SelectOption is one choice in a SelectEl.
type SelectOption struct {
	Value string
	Label string
}

// SelectEl is a single-choice dropdown (HTML <select>) / cycling picker
// (TUI: left/right or space cycles the selection).
type SelectEl struct {
	ID       string
	Options  []SelectOption
	Value    string
	OnChange func(value string) Msg
	Style    Style
	Disabled bool
}

// TextAreaEl is a multi-line text input.
type TextAreaEl struct {
	ID          string
	Value       string
	Placeholder string
	Rows        int // visible lines; 0 = default (4)
	OnChange    func(string) Msg
	Style       Style
	Disabled    bool
}

func (TextEl) isElement()       {}
func (BoxEl) isElement()        {}
func (ButtonEl) isElement()     {}
func (TextInputEl) isElement()  {}
func (FormEl) isElement()       {}
func (CheckboxEl) isElement()   {}
func (CardEl) isElement()       {}
func (ListEl) isElement()       {}
func (ScrollAreaEl) isElement() {}
func (LinkEl) isElement()       {}
func (TableEl) isElement()      {}
func (EmptyEl) isElement()      {}
func (SpacerEl) isElement()     {}
func (DividerEl) isElement()    {}
func (ProgressEl) isElement()   {}
func (SpinnerEl) isElement()    {}
func (SelectEl) isElement()     {}
func (TextAreaEl) isElement()   {}

// spinnerFrames is the glyph cycle used by SpinnerEl in both renderers,
// so an app's frame counter animates identically on either platform.
var spinnerFrames = []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"}

// spinnerGlyph returns the glyph for a frame index, wrapping around and
// tolerating negative counters.
func spinnerGlyph(frame int) string {
	n := len(spinnerFrames)
	i := frame % n
	if i < 0 {
		i += n
	}
	return spinnerFrames[i]
}

// SpinnerFrames returns the number of distinct spinner glyphs, for apps
// that want to keep their frame counter bounded.
func SpinnerFrames() int { return len(spinnerFrames) }

// clampUnit constrains a progress value to the 0..1 range.
func clampUnit(v float64) float64 {
	if v < 0 {
		return 0
	}
	if v > 1 {
		return 1
	}
	return v
}

// selectLabel returns the label to display for the currently selected
// value, falling back to the value itself, then to the first option.
func selectLabel(e SelectEl) string {
	for _, o := range e.Options {
		if o.Value == e.Value {
			if o.Label != "" {
				return o.Label
			}
			return o.Value
		}
	}
	if e.Value != "" {
		return e.Value
	}
	if len(e.Options) > 0 {
		if e.Options[0].Label != "" {
			return e.Options[0].Label
		}
		return e.Options[0].Value
	}
	return ""
}

// selectCycle returns the value delta options away from the current
// selection, wrapping at both ends. An unknown current value starts
// from the first option.
func selectCycle(e SelectEl, delta int) string {
	if len(e.Options) == 0 {
		return e.Value
	}
	idx := 0
	for i, o := range e.Options {
		if o.Value == e.Value {
			idx = i
			break
		}
	}
	n := len(e.Options)
	next := (idx + delta) % n
	if next < 0 {
		next += n
	}
	return e.Options[next].Value
}

// selectChangeMsg produces the Msg for selecting value: the OnChange
// callback when set, else a generic InputMsg.
func selectChangeMsg(e SelectEl, value string) Msg {
	if e.OnChange != nil {
		return e.OnChange(value)
	}
	return InputMsg{ID: e.ID, Value: value}
}

// Children returns el's child elements, or nil for leaves. It is the
// single place that knows the shape of the tree, so walkers (focus
// collection, form value gathering, lookups) do not each have to
// enumerate every container type.
func Children(el Element) []Element {
	switch v := el.(type) {
	case BoxEl:
		return v.Children
	case FormEl:
		return v.Children
	case ListEl:
		return v.Items
	case ScrollAreaEl:
		if v.Child == nil {
			return nil
		}
		return []Element{v.Child}
	case CardEl:
		if v.Child == nil {
			return nil
		}
		return []Element{v.Child}
	case ResponsiveEl:
		// Every variant counts as a child. Which one draws depends on
		// the width available at render time, which Children cannot
		// know, so lookups (Walk, Find, form value collection) see
		// them all. Focus collection deliberately does not use this:
		// it resolves the single visible variant instead, so hidden
		// controls stay out of the tab ring.
		out := make([]Element, 0, len(v.Variants))
		for _, b := range v.Variants {
			if b.Content != nil {
				out = append(out, b.Content)
			}
		}
		return out
	}
	return nil
}

// styleOf returns the Style carried by el, when its type has one. It
// is how a Box reads layout hints (Grow, MinWidth) off its children
// without enumerating element types at every call site.
func styleOf(el Element) (Style, bool) {
	switch v := el.(type) {
	case TextEl:
		return v.Style, true
	case BoxEl:
		return v.Style, true
	case ButtonEl:
		return v.Style, true
	case TextInputEl:
		return v.Style, true
	case FormEl:
		return v.Style, true
	case ListEl:
		return v.Style, true
	case ScrollAreaEl:
		return v.Style, true
	case CheckboxEl:
		return v.Style, true
	case CardEl:
		return v.Style, true
	case LinkEl:
		return v.Style, true
	case TableEl:
		return v.Style, true
	case DividerEl:
		return v.Style, true
	case ProgressEl:
		return v.Style, true
	case SpinnerEl:
		return v.Style, true
	case SelectEl:
		return v.Style, true
	case TextAreaEl:
		return v.Style, true
	}
	return Style{}, false
}

// Walk calls fn for el and every descendant, depth-first in tree order.
// Returning false from fn skips that element's children.
func Walk(el Element, fn func(Element) bool) {
	if el == nil {
		return
	}
	if !fn(el) {
		return
	}
	for _, c := range Children(el) {
		Walk(c, fn)
	}
}

// Find returns the first element in tree order for which pred holds.
func Find(el Element, pred func(Element) bool) (Element, bool) {
	var found Element
	Walk(el, func(e Element) bool {
		if found != nil {
			return false
		}
		if pred(e) {
			found = e
			return false
		}
		return true
	})
	return found, found != nil
}

// buttonFocusKey derives a button's stable identity — used as the TUI
// focus-ring key and the DOM id: the explicit ID when set, else the
// label. Buttons sharing a label (and no ID) in one view share a key.
func buttonFocusKey(e ButtonEl) string {
	if e.ID != "" {
		return "btn:" + e.ID
	}
	return "btn:" + e.Label
}

// checkboxToggleMsg produces the Msg for toggling a checkbox to the
// given state: the OnToggle callback when set, else a generic ToggleMsg.
func checkboxToggleMsg(e CheckboxEl, checked bool) Msg {
	if e.OnToggle != nil {
		return e.OnToggle(checked)
	}
	return ToggleMsg{ID: e.ID, Checked: checked}
}

// Text creates a text node.
func Text(s string, opts ...func(*TextEl)) Element {
	e := TextEl{Content: s}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithTextStyle sets style on a TextEl built via Text.
func WithTextStyle(s Style) func(*TextEl) {
	return func(e *TextEl) { e.Style = s }
}

// Box creates a flex container laid out along dir.
func Box(dir Direction, children ...Element) Element {
	return BoxEl{Direction: dir, Children: children}
}

// BoxStyled creates a flex container with explicit style and gap.
func BoxStyled(dir Direction, gap int, style Style, children ...Element) Element {
	return BoxEl{Direction: dir, Gap: gap, Style: style, Children: children}
}

// Button creates a clickable button.
func Button(label string, onClick func() Msg, opts ...func(*ButtonEl)) Element {
	e := ButtonEl{Label: label, OnClick: onClick}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithButtonStyle sets style on a ButtonEl.
func WithButtonStyle(s Style) func(*ButtonEl) {
	return func(e *ButtonEl) { e.Style = s }
}

// WithID gives a button an explicit stable identity. Without it the
// focus key derives from the label, so two buttons sharing a label in
// one view would share focus; an ID also lets the browser restore
// focus to the button across re-renders.
func WithID(id string) func(*ButtonEl) {
	return func(e *ButtonEl) { e.ID = id }
}

// Disabled marks a ButtonEl as disabled.
func Disabled() func(*ButtonEl) {
	return func(e *ButtonEl) { e.Disabled = true }
}

// Input creates a text input field identified by id.
func Input(id string, opts ...func(*TextInputEl)) Element {
	e := TextInputEl{ID: id}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithValue sets the current value of a TextInputEl.
func WithValue(v string) func(*TextInputEl) {
	return func(e *TextInputEl) { e.Value = v }
}

// WithPlaceholder sets placeholder text on a TextInputEl.
func WithPlaceholder(p string) func(*TextInputEl) {
	return func(e *TextInputEl) { e.Placeholder = p }
}

// WithPassword marks a TextInputEl as a password field.
func WithPassword() func(*TextInputEl) {
	return func(e *TextInputEl) { e.Password = true }
}

// WithOnChange sets the change handler on a TextInputEl.
func WithOnChange(f func(string) Msg) func(*TextInputEl) {
	return func(e *TextInputEl) { e.OnChange = f }
}

// WithOnSubmit sets the submit handler on a TextInputEl (Enter key).
func WithOnSubmit(f func(string) Msg) func(*TextInputEl) {
	return func(e *TextInputEl) { e.OnSubmit = f }
}

// Checkbox creates a toggleable checkbox with a text label. id must be
// stable and unique — it identifies the checkbox in the focus ring and
// the DOM. onToggle receives the new checked state; pass nil to get a
// generic ToggleMsg instead.
func Checkbox(id, label string, checked bool, onToggle func(bool) Msg, opts ...func(*CheckboxEl)) Element {
	e := CheckboxEl{ID: id, Label: label, Checked: checked, OnToggle: onToggle}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithCheckboxStyle sets style on a CheckboxEl.
func WithCheckboxStyle(s Style) func(*CheckboxEl) {
	return func(e *CheckboxEl) { e.Style = s }
}

// CheckboxDisabled marks a CheckboxEl as disabled.
func CheckboxDisabled() func(*CheckboxEl) {
	return func(e *CheckboxEl) { e.Disabled = true }
}

// Card wraps a child in a titled, bordered panel. The TUI draws the
// title embedded in the top border; HTML renders <fieldset><legend>.
func Card(title string, child Element, opts ...func(*CardEl)) Element {
	e := CardEl{Title: title, Child: child}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithCardStyle sets style on a CardEl. Border is implied; Padding,
// Margin, Width and BorderColor apply.
func WithCardStyle(s Style) func(*CardEl) {
	return func(e *CardEl) { e.Style = s }
}

// Form creates a form container that collects input values on submit.
func Form(onSubmit func(map[string]string) Msg, children ...Element) Element {
	return FormEl{OnSubmit: onSubmit, Children: children}
}

// List creates a list of items, ordered or unordered.
func List(ordered bool, items ...Element) Element {
	return ListEl{Ordered: ordered, Items: items}
}

// Scroll wraps a child in a scrollable area capped at maxHeight.
func Scroll(child Element, maxHeight int) Element {
	return ScrollAreaEl{Child: child, MaxHeight: maxHeight}
}

// Link creates a navigable link.
func Link(label, href string) Element {
	return LinkEl{Label: label, Href: href}
}

// Table creates a tabular display.
func Table(columns []string, rows [][]string) Element {
	return TableEl{Columns: columns, Rows: rows}
}

// Empty renders nothing. Use it as the "else" branch of a conditional
// view instead of returning nil.
func Empty() Element { return EmptyEl{} }

// Spacer inserts n cells (in a Row) or n blank lines (in a Column) of
// empty space between siblings.
func Spacer(n int) Element { return SpacerEl{Size: n} }

// Flex inserts stretchy empty space that pushes the siblings on either
// side apart — the idiom for pinning one child to the far end of a Row.
// In the TUI it expands to fill the Box's remaining width; in HTML it
// is flex:1.
func Flex() Element { return SpacerEl{} }

// Divider draws a horizontal rule. Pass "" for an unlabelled rule.
func Divider(label string, opts ...func(*DividerEl)) Element {
	e := DividerEl{Label: label}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithDividerStyle sets style on a DividerEl. Width bounds the rule;
// without it the rule fills the available width.
func WithDividerStyle(s Style) func(*DividerEl) {
	return func(e *DividerEl) { e.Style = s }
}

// Progress creates a determinate progress bar. value is clamped to
// 0..1.
func Progress(value float64, opts ...func(*ProgressEl)) Element {
	e := ProgressEl{Value: clampUnit(value)}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithProgressWidth sets the bar width in cells (pixels-equivalent ch
// units in HTML).
func WithProgressWidth(n int) func(*ProgressEl) {
	return func(e *ProgressEl) { e.Width = n }
}

// WithProgressLabel appends a percentage readout after the bar.
func WithProgressLabel() func(*ProgressEl) {
	return func(e *ProgressEl) { e.ShowLabel = true }
}

// WithProgressStyle sets style on a ProgressEl; FG colors the filled
// portion.
func WithProgressStyle(s Style) func(*ProgressEl) {
	return func(e *ProgressEl) { e.Style = s }
}

// WithProgressRunes overrides the TUI fill and track glyphs. It has no
// effect in HTML, which draws a real bar.
func WithProgressRunes(filled, empty string) func(*ProgressEl) {
	return func(e *ProgressEl) {
		e.FilledRune = filled
		e.EmptyRune = empty
	}
}

// Spinner creates an activity indicator showing the given animation
// frame. Advance frame from a Tick Cmd:
//
//	case tickMsg:
//	    m.frame++
//	    return m, wui.Tick(100*time.Millisecond, func() wui.Msg { return tickMsg{} })
func Spinner(frame int, opts ...func(*SpinnerEl)) Element {
	e := SpinnerEl{Frame: frame}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithSpinnerLabel sets text shown next to the spinner glyph.
func WithSpinnerLabel(label string) func(*SpinnerEl) {
	return func(e *SpinnerEl) { e.Label = label }
}

// WithSpinnerStyle sets style on a SpinnerEl.
func WithSpinnerStyle(s Style) func(*SpinnerEl) {
	return func(e *SpinnerEl) { e.Style = s }
}

// Opt builds a SelectOption. Pass an empty label to display the value.
func Opt(value, label string) SelectOption {
	return SelectOption{Value: value, Label: label}
}

// Options builds a SelectOption slice from values, using each value as
// its own label.
func Options(values ...string) []SelectOption {
	out := make([]SelectOption, 0, len(values))
	for _, v := range values {
		out = append(out, SelectOption{Value: v, Label: v})
	}
	return out
}

// Select creates a single-choice picker. id must be stable and unique.
// In HTML it is a <select>; in the TUI it is a focusable field that
// cycles through options with left/right (or Space/Enter).
func Select(id string, options []SelectOption, value string, onChange func(string) Msg, opts ...func(*SelectEl)) Element {
	e := SelectEl{ID: id, Options: options, Value: value, OnChange: onChange}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithSelectStyle sets style on a SelectEl.
func WithSelectStyle(s Style) func(*SelectEl) {
	return func(e *SelectEl) { e.Style = s }
}

// SelectDisabled marks a SelectEl as disabled.
func SelectDisabled() func(*SelectEl) {
	return func(e *SelectEl) { e.Disabled = true }
}

// TextArea creates a multi-line text input identified by id.
func TextArea(id string, opts ...func(*TextAreaEl)) Element {
	e := TextAreaEl{ID: id}
	for _, opt := range opts {
		opt(&e)
	}
	return e
}

// WithAreaValue sets the current value of a TextAreaEl.
func WithAreaValue(v string) func(*TextAreaEl) {
	return func(e *TextAreaEl) { e.Value = v }
}

// WithAreaPlaceholder sets placeholder text on a TextAreaEl.
func WithAreaPlaceholder(p string) func(*TextAreaEl) {
	return func(e *TextAreaEl) { e.Placeholder = p }
}

// WithAreaRows sets the visible line count of a TextAreaEl.
func WithAreaRows(n int) func(*TextAreaEl) {
	return func(e *TextAreaEl) { e.Rows = n }
}

// WithAreaOnChange sets the change handler on a TextAreaEl.
func WithAreaOnChange(f func(string) Msg) func(*TextAreaEl) {
	return func(e *TextAreaEl) { e.OnChange = f }
}

// WithAreaStyle sets style on a TextAreaEl.
func WithAreaStyle(s Style) func(*TextAreaEl) {
	return func(e *TextAreaEl) { e.Style = s }
}

// AreaDisabled marks a TextAreaEl as disabled.
func AreaDisabled() func(*TextAreaEl) {
	return func(e *TextAreaEl) { e.Disabled = true }
}

// If renders el when cond holds, and nothing otherwise — so a view can
// stay a single expression:
//
//	wui.Box(wui.Column,
//	    wui.If(m.err != "", wui.Text(m.err)),
//	    wui.Text("ready"),
//	)
func If(cond bool, el Element) Element {
	if !cond {
		return Empty()
	}
	return orEmpty(el)
}

// IfElse renders yes when cond holds, else no.
func IfElse(cond bool, yes, no Element) Element {
	if cond {
		return orEmpty(yes)
	}
	return orEmpty(no)
}

// When renders the result of build when cond holds. Unlike If, build is
// only called when needed — use it when constructing the element is
// costly or would panic on the false branch.
func When(cond bool, build func() Element) Element {
	if !cond || build == nil {
		return Empty()
	}
	return orEmpty(build())
}

// Map builds one Element per item — the loop that every View writes by
// hand, as an expression:
//
//	wui.List(false, wui.Map(m.items, func(i int, s string) wui.Element {
//	    return wui.Text(s)
//	})...)
func Map[T any](items []T, build func(i int, item T) Element) []Element {
	out := make([]Element, 0, len(items))
	for i, item := range items {
		out = append(out, orEmpty(build(i, item)))
	}
	return out
}

// Group combines children into one Element without adding layout of its
// own beyond stacking them vertically. Use it where a single Element is
// required but several must be returned.
func Group(children ...Element) Element {
	return groupOf(children)
}

// Row is shorthand for Box(Row, ...) with a one-cell gap.
func HStack(children ...Element) Element {
	return BoxStyled(Row, 1, Style{}, children...)
}

// VStack is shorthand for Box(Column, ...) with no gap.
func VStack(children ...Element) Element {
	return BoxStyled(Column, 0, Style{}, children...)
}

// Center horizontally centers children within width cells.
func Center(width int, children ...Element) Element {
	return BoxStyled(Column, 0, Style{Width: width, Align: AlignCenter}, children...)
}