Documentation
¶
Overview ¶
Package tui is dbc's Bubble Tea v2 terminal interface: connections and tables sidebar, SQL editor, results grid, log, AI assistant, with the mouse as a first-class input.
HOW A FRAME IS MADE. Bubble Tea asks the model for a View, which is one styled string. Rather than assembling that string from lipgloss blocks joined side by side, every frame is DRAWN into a Canvas — a grid of cells, each a grapheme plus a style — and the canvas is serialized once at the end:
layout(w, h) ──► rects for every pane, button and splitter
│
├──► draw: each widget paints inside its rect on the Canvas
│ overlays (menus, modals) paint last, on top
│
└──► hit-test: a click is resolved against THE SAME rects
This is cats-todo's rule — one layout description both draws and hit-tests, so the two cannot drift — made structural. With string joins the rule holds only as long as no line above a clickable one ever wraps; with a canvas a widget cannot draw outside its rect at all (Surface clips), so a long value in one pane can never shift a click target in another. Overlays need no compositor: they are simply drawn after the base.
Index ¶
- func OpenURL(u string)
- func Run(cfg *config.Config, mgr *db.Manager) error
- type Attr
- type Canvas
- type Color
- type Model
- type Options
- type Rect
- type Style
- type Surface
- func (s Surface) Box(border Style, title string, titleSt Style)
- func (s Surface) Fill(st Style)
- func (s Surface) H() int
- func (s Surface) Put(x, y int, text string, st Style) int
- func (s Surface) PutRight(right, y int, text string, st Style) int
- func (s Surface) Rect() Rect
- func (s Surface) Restyle(f func(Style) Style)
- func (s Surface) Sub(r Rect) Surface
- func (s Surface) W() int
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Canvas ¶
type Canvas struct {
W, H int
// contains filtered or unexported fields
}
Canvas is one frame being drawn.
func (*Canvas) Line ¶
Line returns row y as plain text, wide cells counted once — for tests, which assert on what is on screen without caring how it is colored.
func (*Canvas) String ¶
String serializes the canvas as the styled string Bubble Tea renders. A style escape is emitted only when the style changes, and each line ends with a reset so a style can never bleed into the terminal's margin.
type Color ¶
type Color uint32
Color is a 24-bit RGB color with a "set" flag above it. The zero Color is the terminal's own default, so the zero Style is "default on default" — the safe reading of a style nobody filled in — and black is still representable, as a set color whose RGB happens to be zero.
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
Model is the whole application state, and the Bubble Tea model.
ONE MODEL, PLAIN WIDGETS. As in cats-todo, there are no nested tea.Models: the editor, grid, lists and panes are ordinary structs the Model owns and calls. Messages are routed here, in one place, which is what lets a mouse click decide between "focus this pane", "start dragging a splitter" and "dismiss a menu" before any widget sees it.
THE THREADING RULE. Only Update mutates the Model. Work that blocks — a query, a connect, a clipboard write, the AI agent — runs as a tea.Cmd (a function Bubble Tea calls on its own goroutine) and reports back with a message. The database side of that — the active connection, the run slot, the pinned session, the last statement, error, result and plan — is not the Model's at all but the workspace's (ws), which the browser UI shares and which guards itself with its own mutexes: a run's Job lands its outcome there from the command goroutine, and Update draws the event.
It is a pointer receiver throughout: the model is large, and every Update returning a copy of it would copy the editor buffer and the result on every mouse motion.
func New ¶
New builds the model. It does no IO beyond reading the history and saved buffer; connecting happens in Init's command.
type Options ¶
type Options struct {
// NoPersist keeps the history, buffer and conversations off disk —
// tests, which must not read or clobber the developer's real
// ~/.config/dbc.
NoPersist bool
}
Options configure New beyond what the config holds.
type Rect ¶
type Rect struct{ X, Y, W, H int }
Rect is a rectangle of cells. The zero Rect is empty and contains nothing, which is what a hidden pane's rect is.
type Style ¶
Style is how one cell is painted.
type Surface ¶
type Surface struct {
// contains filtered or unexported fields
}
Surface is a clipped view of a canvas: coordinates are relative to its rect, and nothing drawn through it can land outside. Every widget draws through one, which is what guarantees a pane cannot spill into another.
func (Surface) Box ¶
Box draws a single-line border around the whole surface with an optional title in the top edge. The inside is left alone.
func (Surface) Put ¶
Put draws text at (x, y) relative to the surface, one grapheme at a time, clipped to the surface. It returns the column after the last cell drawn, so runs of differently styled text chain: x = s.Put(x, y, a, st1); x = s.Put(x, y, b, st2).
Control characters are drawn as a middle dot: a raw tab or newline inside a value (a multi-line TEXT column) would otherwise move the terminal's cursor and tear the frame apart.
func (Surface) PutRight ¶
PutRight draws text right-aligned so it ends at column right (exclusive), returning where it started.
func (Surface) Restyle ¶
Restyle applies f to the style of every cell in the surface without touching the text — how a selection or hover highlight is laid over content that was drawn normally.
Source Files