# gleamtea [![Package Version](https://img.shields.io/hexpm/v/gleamtea)](https://hex.pm/packages/gleamtea) [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gleamtea/) **A delightful terminal UI framework for Gleam** — typed bindings to [beamtea](https://hex.pm/packages/beamtea), which is [Bubble Tea](https://github.com/charmbracelet/bubbletea) / The Elm Architecture for the BEAM, built on `prim_tty`. Write your terminal app as three pure functions — `init`, `update`, `view` — and gleamtea owns the terminal, decodes keypresses, runs your commands, and repaints the screen. ![gleamtea preview](.github/assets/preview.png) ```gleam import gleamtea.{type Cmd, type Event, Key, None, Quit} import gleamtea/color import gleamtea/key.{Char, Down, Up} import gleamtea/term import gleam/int pub fn main() { gleamtea.program(init:, update:, view:) |> gleamtea.start } fn init() -> #(Int, Cmd(Event(Nil))) { #(0, None) } fn update(msg: Event(Nil), n: Int) -> #(Int, Cmd(Event(Nil))) { case msg { Key(Up) -> #(n + 1, None) Key(Down) -> #(n - 1, None) Key(Char(113)) -> #(n, Quit) // q _ -> #(n, None) } } fn view(n: Int) -> String { color.fg(color.Charmple, term.bold("count: " <> int.to_string(n))) } ``` --- ## Why this is (almost) all types and no glue beamtea speaks plain Erlang terms: the atom `quit`, the tuple `{tick, 1000, Msg}`, a keypress `{key, up}`. Gleam's custom types compile to *exactly* those terms — so the binding is mostly a set of type definitions with zero marshalling cost. | Gleam | Erlang term (beamtea) | | ------------------------ | -------------------------- | | `Quit` | `quit` | | `Tick(1000, msg)` | `{tick, 1000, Msg}` | | `Key(Up)` | `{key, up}` | | `Key(Char(97))` | `{key, {char, 97}}` | | `Key(Ctrl(99))` | `{key, {ctrl, 99}}` | The escapes and colours (`gleamtea/term`, `gleamtea/color`) and the reusable components (`gleamtea/spinner`, `gleamtea/table`, …) are thin FFI wrappers that flatten beamtea's `iodata()` into ordinary Gleam `String`s. --- ## Installation ```sh gleam add gleamtea ``` `beamtea` (an Erlang/rebar3 package) is pulled in automatically as a dependency; Gleam builds it with rebar3. --- ## The Elm Architecture A program is three functions, wired together with `gleamtea.program`: - **`init() -> #(model, Cmd(msg))`** — the starting model and an initial command. - **`update(msg, model) -> #(model, Cmd(msg))`** — fold a message into the model. - **`view(model) -> String`** — render the model to the full screen. Your message type is always `Event(user)`: ```gleam pub type Event(user) { Key(Key) // a keypress — see gleamtea/key Resize(#(Int, Int)) // the terminal was resized to #(cols, rows) User(user) // one of your own messages } ``` Keyboard and resize events arrive as `Key(...)` / `Resize(...)`. Your own messages — produced by commands like `Tick`, `Every` and `Task` — arrive wrapped in `User(...)`, so everything stays type-safe. ### Commands Return a `Cmd(msg)` from `init`/`update` to ask the runtime to do something: | Command | Effect | | ------------------- | ------------------------------------------------------------ | | `None` | do nothing | | `Quit` | quit after this update | | `Msg(m)` | deliver `m` to `update` as soon as possible | | `Tick(ms, m)` | deliver `m` once, after `ms` milliseconds | | `Every(ms, m)` | deliver `m` repeatedly, every `ms` milliseconds | | `Task(fn)` | run `fn` asynchronously; its result is delivered to `update` | | `Batch([...])` | run several commands | | `Seq([...])` | run several commands in sequence | ```gleam // tick every 100 ms #(model, Every(100, User(Tick))) ``` --- ## Modules ### Core | Module | What it gives you | | ----------------- | ------------------------------------------------------------ | | `gleamtea` | `program`, `start`, `start_with`, `Event`, `Cmd`, `Options`, `Layout`, `window_size` | | `gleamtea/key` | the `Key` type (`Up`, `Enter`, `Ctrl(_)`, `Char(_)`, …) | | `gleamtea/term` | ANSI escapes: `bold`, `faint`, `reverse`, `move`, `clear`, `fg_rgb`, `rule`, … | | `gleamtea/color` | the Charm-inspired palette (`Charmple`, `Hotpink`, `Cyan`, …) | | `gleamtea/style` | lipgloss-style blocks: colour, border, padding, align, `join_*` | | `gleamtea/layout` | position content: `center`, `frame`, `place`, `overlay_center` | | `gleamtea/util` | ANSI-aware `lines`, `pad_visible`, `truncate`, `visible_width` | ### Bubbles (reusable components) | Module | Component | | ---------------------- | ------------------------------------------- | | `gleamtea/spinner` | animated spinner (8 styles) | | `gleamtea/progress` | truecolor gradient progress bar | | `gleamtea/timer` | countdown timer | | `gleamtea/list` | scrollable, selectable list | | `gleamtea/table` | scrollable, row-selectable data table | | `gleamtea/textinput` | single-line text input | | `gleamtea/textarea` | multi-line text editor | | `gleamtea/viewport` | scrollable viewport over a block of text | | `gleamtea/filepicker` | filesystem picker | | `gleamtea/paginator` | paginator (dots or "N/M") | | `gleamtea/keybind` | declarative key bindings | | `gleamtea/help` | help view that renders `keybind` bindings | A bubble is a little model with its own `update`/`view`. Store it in your model, render it in your `view`, and **forward messages you don't handle to its `update`** — self-animating bubbles (spinner, timer) keep themselves running by returning their next tick: ```gleam fn update(msg: Msg, model: Model) -> #(Model, Cmd(Msg)) { case msg { Key(Char(113)) -> #(model, Quit) // q other -> { let #(spinner, cmd) = spinner.update(other, model.spinner) #(Model(..model, spinner:), cmd) } } } ``` --- ## Styling & layout (beamtea 0.1.2) `gleamtea/style` is a composable, lipgloss-inspired styling layer. Build a `Style` with piped setters, then `render` it onto text — inline attributes (colour, bold) compose with block layout (width, alignment, padding, border): ```gleam import gleamtea/style import gleamtea/color style.new() |> style.foreground(style.Named(color.Charmple)) |> style.bold |> style.padding(style.VH(1, 3)) |> style.border(style.Rounded) |> style.border_foreground(style.Rgb(0xEE, 0x6F, 0xF8)) // 24-bit truecolor |> style.render("Hello, style!") ``` Colours can be a palette `Named(_)`, a raw xterm `Index(_)`, or 24-bit `Rgb(r, g, b)`. Compose rendered blocks with `style.join_horizontal` and `style.join_vertical`. `gleamtea/layout` positions a block within the terminal — pair it with `gleamtea.window_size()` to size to the screen from inside your `view`: ```gleam import gleamtea/layout let #(cols, rows) = gleamtea.window_size() layout.center(card, cols, rows) // centre a block layout.frame(content, cols, rows, color.Indigo) // bordered full-screen panel layout.overlay_center(background, modal, cols, rows) // float a modal ``` Or let the runtime position the *whole* view automatically (it re-flows on resize) with the `layout` option — `TopLeft` (default), `Center`, `TopCenter` or `Fill`: ```gleam gleamtea.start_with(program, gleamtea.Options( alt_screen: True, catch_ctrl_c: True, layout: gleamtea.Center, )) ``` --- ## Running a program A full-screen TUI needs to own the terminal: raw mode, the alternate screen, and Ctrl-C delivered as a byte rather than a signal. Don't launch from an interactive `gleam run` (its shell fights you for the terminal). Instead use the included launcher, which starts the VM with `-noshell -noinput +Bi` and puts the tty in raw mode: ```sh ./bin/gleamtea-run counter ``` Under the hood it runs the compiled example's `main/0`; do the same for your own app once it's compiled. ### Options ```gleam gleamtea.program(init:, update:, view:) |> gleamtea.start_with(gleamtea.Options( alt_screen: True, catch_ctrl_c: True, layout: gleamtea.TopLeft, )) ``` - `alt_screen` — use the alternate screen buffer (like `vim`/`less`). Default `True`. - `catch_ctrl_c` — quit on Ctrl-C instead of passing it to `update`. Default `True`. - `layout` — position the whole view: `TopLeft` (default), `Center`, `TopCenter`, `Fill`. `start` / `start_with` return `Ok(final_model)` on a clean exit, or `Error(reason)` if the program could not start (e.g. stdout is not a terminal). --- ## Examples Nineteen runnable examples live in [`src/examples/`](src/examples). Run any of them with the launcher: ```sh ./bin/gleamtea-run ``` | Example | Shows off | | ------------------ | ----------------------------------------------- | | `counter` | the core loop — no bubbles | | `keys` | how raw input decodes into key events | | `stopwatch` | `Every` timers and a `User` message | | `palette` | the full colour palette | | `spinner_demo` | the spinner bubble, cycling styles | | `progress_demo` | a self-filling truecolor gradient bar + `Every` | | `timer_demo` | a 10-second countdown | | `list_demo` | a scrollable, selectable menu | | `table_demo` | a selectable data table | | `textinput_demo` | a focused text field with a live greeting | | `textarea_demo` | a multi-line editor in a bordered box | | `viewport_demo` | scrolling through a long document | | `filepicker_demo` | browsing the filesystem | | `help_demo` | key bindings + help + paginator | | `dashboard_demo` | a grid of styled stat cards (`style` composition) | | `statusbar_demo` | a full-width vim-style status bar | | `tabs_demo` | a tabbed interface with a bordered panel | | `modal_demo` | a floating yes/no modal over a backdrop | | `finder_demo` | an fzf-style fuzzy finder in a floating modal | --- ## Development ```sh gleam build # compile the library, bindings and examples gleam test # run the test suite gleam docs build # generate HTML docs into build/dev/docs ./bin/gleamtea-run counter ``` --- ## Credits gleamtea is a thin Gleam layer over [beamtea](https://github.com/tsirysndr/beamtea) by Tsiry Sandratraina, which is itself inspired by Charmbracelet's [Bubble Tea](https://github.com/charmbracelet/bubbletea) and [Bubbles](https://github.com/charmbracelet/bubbles). ## License [MIT](LICENSE)