go-tui Framework

The GSX Language Server is an LSP (Language Server Protocol) implementation specifically for .gsx files. It provides real-time editor intelligence features including:

• Hover: Documentation on hover.
• Completion: Code completion suggestions.
• Go-to-definition: Navigating to where an element is defined.
• Find-references: Locating all usages of an element.
• Diagnostics: Real-time error and warning reporting.
• Formatting: Document auto-formatting.
• Semantic tokens: Semantic token highlighting.
• Symbols: Document and workspace-wide symbol discovery.

Understanding the project layout helps in locating core logic and generated files:

• cmd/tui/: Contains the tui CLI tool source.
• pkg/tui/: The core TUI engine (app loop, buffer, rendering, widgets).
• pkg/layout/: The layout engine (calculation, nodes, styles).
• pkg/tuigen/: The code generation logic (lexer, parser, generator).
• examples/: Sample applications (hello, dashboard, form).

.gsx files are Go files extended with a templ-like syntax for declaring UI. They support standard Go package declarations, imports, and type definitions. The templ keyword is used to define components that return element trees.

To use GSX, run the tui generate command, which reads .gsx files and produces standard _gsx.go files that call the tui package API. Note: You should never edit the generated _gsx.go files directly.

go-tui provides three core built-in components for building terminal user interfaces:

1. Input: A single-line text input component with cursor management, horizontal scrolling, and placeholder support.
2. TextArea: A multi-line text input component.
3. Modal: An overlay dialog component that handles backdrop rendering, focus trapping, and preemptive key blocking.

All three components implement the Component, KeyListener, and AppBinder interfaces.

Important Usage Note: When using these as GSX elements (<input>, <textarea>, <modal>), they must be mounted against a component's receiver. Therefore, place them inside a struct method component rather than a pure templ function. The same rule applies to the <markdown> element.

A Ref is a pointer to a single element in the rendered tree, allowing you to interact with it from Go code. You create a ref using tui.NewRef() and attach it to an element in your GSX template using the ref attribute.

Important: Before the first render, ref.El() returns nil. Always perform a nil check before accessing the element.

type myApp struct {
    saveBtn *tui.Ref
}

func MyApp() *myApp {
    return &myApp{
        saveBtn: tui.NewRef(),
    }
}

templ (a *myApp) Render() {
    <button ref={a.saveBtn} class="px-2">Save</button>
}

// Accessing the element safely
if el := a.saveBtn.El(); el != nil {
    // safe to use el
}

Choose between PrintAbove and StreamAbove based on your output requirements:

go-tui uses a CSS flexbox-compatible layout engine. Every <div> acts as a flex container, and its children are flex items. You can arrange children using a main axis (the direction children flow) and a cross axis (perpendicular to the main axis).

Layout controls can be applied in two ways:

1. Tailwind-style classes: Using strings like flex-col, justify-center, or gap-2 in the class attribute.
2. Element attributes: Using typed attributes like direction={tui.Column}, justify={tui.JustifyCenter}, or gap={2}.

Focus can be managed at the element level (element.Focus(), element.Blur()) or the app level (app.FocusNext(), app.FocusPrev()).

For section-level switching (e.g., between a sidebar and content), use a FocusGroup. A FocusGroup created with tui.MustNewFocusGroup(compA, compB) allows cycling focus between its members using fg.Next() or fg.Prev(). The group's KeyMap() automatically provides Tab and Shift+Tab bindings.

// FocusGroup example
sidebar := tui.NewState(true)
content := tui.NewState(false)
fg := tui.MustNewFocusGroup(sidebar, content)
fg.Next() // Cycles focus

A KeyMatcher defines which key events a binding should respond to. You can use three types of matchers:

• Key constants: Use tui.KeyEscape, tui.KeyEnter, etc., to match specific special keys.
• tui.Rune(r rune): Matches a specific printable character.
• tui.AnyRune: Matches any printable character.

All matchers support modifier methods to require specific combinations:

• .Shift()
• .Ctrl()
• .Alt()

tui.KeyUp.Shift()       // Match Shift+Up
tui.KeyUp.Ctrl()        // Match Ctrl+Up
tui.KeyUp.Alt()         // Match Alt+Up
tui.Rune('s').Ctrl()    // Match Ctrl+S
tui.Rune('x').Alt()     // Match Alt+X