#moonbit-community/rabbita_tui

Warning: moonbit-community/rabbita_tui is experimental. Public APIs, package layout, widget names, and runtime behavior may change while it converges with Rabbita.

terminal event / command result
          |
          v
        Msg ------> update(emit, msg, model) -> (Cmd, Model)
          ^                                  |
          |                                  v
        Cmd <----------------------------- view(model)

• Emit[Msg] turns a message into a monomorphic Cmd.
• Cmd is not parameterized by Msg.
• cell owns Model, update, view, and subscriptions.
• Dispatch is kept only as a deprecated alias for Emit.

#Install

{
  "deps": {
    "moonbit-community/rabbita_tui": "0.1.0",
    "moonbitlang/async": "0.17.0"
  },
  "preferred-target": "native"
}

import {
  "moonbit-community/rabbita_tui" @tui,
  "moonbit-community/rabbita_tui/widgets" @widgets,
  "moonbitlang/async",
}

supported_targets = "+native"

options(
  "is-main": true,
)

moon run --target native path/to/your/package

#A Complete Small App

///|
using @tui {
  border,
  cell,
  pad,
  text,
  type Cmd,
  type Edge,
  type Emit,
  type Frame,
  type Key,
  type Node,
  type ProgramOptions,
  type Size,
  type Style,
  type Sub,
  vstack,
}

///|
using @widgets {status_line}

///|
enum Msg {
  KeyPressed(Key)
  Resize(Size)
  Quit
} derive(Eq, Debug)

///|
struct Model {
  count : Int
  width : Int
  height : Int
} derive(Eq, Debug)

///|
fn initial_model() -> Model {
  { count: 0, width: 80, height: 24, }
}

///|
fn update(_emit : Emit[Msg], msg : Msg, model : Model) -> (Cmd, Model) {
  match msg {
    KeyPressed(key) =>
      match key {
        Up => (Cmd::none(), { ..model, count: model.count + 1, })
        Down => (Cmd::none(), { ..model, count: model.count - 1, })
        Char("q") | Ctrl("c") => (Cmd::quit(), model)
        _ => (Cmd::none(), model)
      }
    Resize(size) =>
      (Cmd::none(), { ..model, width: size.width, height: size.height, })
    Quit => (Cmd::quit(), model)
  }
}

///|
fn view(model : Model) -> Node {
  let title = text(style=Style::default().bold().fg(Ansi(39)), "Counter")
  let body = text("count = \{model.count}")
  let help = text("up/down change  q quit")
  let card = vstack(gap=1)  [
    title, body, help,
  ]
  vstack  [
    status_line(
      left="counter",
      right="\{model.width}x\{model.height}",
      width=model.width,
    ),
    vstack(style=Style::default().padding(Edge::all(1)).border())  [
      card,
    ],
  ]
}

///|
fn subscriptions(_model : Model) -> Sub[Msg] {
  Sub::batch([
    Sub::keys(key => KeyPressed(key)),
    Sub::resize(size => Resize(size)),
  ])
}

///|
async fn main {
  cell(model=initial_model(), update~, view~, subscriptions~).run_with_options(
    ProgramOptions::inline(),
  ) catch {
    NotATty(_) =>
      println(
        Frame::from_node(view(initial_model()), { width: 80, height: 24, }).to_string(),
      )
    NativeError(message) => println("terminal error: \{message}")
    UnsupportedPlatform => println("native POSIX terminal required")
  }
}

#Core Concepts

#Model

///|
using @vector {type Vector}

///|
using @widgets {type TextInput}

///|
struct Model {
  input : TextInput
  items : Vector[String]
  selected : Int
  width : Int
  height : Int
}

#Msg

///|
enum Msg {
  Typed(Key)
  Submitted
  Resized(Size)
  Loaded(Result[String, IOError])
  Quit
}

#Update

• emit : Emit[Msg], used to create commands that send messages later.
• msg : Msg, the event to handle.
• model : Model, the current state.

///|
fn update(emit : Emit[Msg], msg : Msg, model : Model) -> (Cmd, Model) {
  match msg {
    Submitted =>
      (delay(emit(Loaded(Ok("done"))), 300), { ..model, status: "loading", })
    Loaded(result) =>
      match result {
        Ok(value) => (Cmd::none(), { ..model, status: value, })
        Err(_) => (Cmd::none(), { ..model, status: "failed", })
      }
    Quit => (Cmd::quit(), model)
    _ => (Cmd::none(), model)
  }
}

///|
fn update(emit : Emit[Msg], msg : Msg, model : Model) -> (Cmd, Model) {
  match msg {
    KeyPressed(key) => update_key(emit, key, model)
    JobFinished(id) => update_job_finished(id, model)
    Resize(size) => (Cmd::none(), resize_model(size, model))
  }
}

#View

///|
fn view(model : Model) -> Node {
  vstack  [
    text(style=Style::default().bold(), "Tasks"),
    border(model.input.view(width=model.width - 4)),
    status_line(left="enter submit", right="q quit", width=model.width),
  ]
}

#Subscriptions

///|
fn subscriptions(_model : Model) -> Sub[Msg] {
  Sub::batch([
    Sub::keys(key => KeyPressed(key)),
    Sub::mouse_events(mouse => MouseSeen(mouse)),
    Sub::paste(value => Pasted(value)),
    Sub::focus_changes(focused => FocusChanged(focused)),
    Sub::resize(size => Resized(size)),
    Sub::tick(100, Tick),
  ])
}

#Commands

///|
fn update(emit : Emit[Msg], msg : Msg, model : Model) -> (Cmd, Model) {
  match msg {
    StartTimer =>
      (delay(emit(TimerDone), 1000), { ..model, status: "waiting", })
    TimerDone => (Cmd::none(), { ..model, status: "done", })
  }
}

Cmd::exec_process(
  "git",
  code => emit(ProcessExited(code)),
)
Cmd::exec_process_with_args(
  "git",
  ["status", "--short"],
  code => emit(ProcessExited(code)),
)

Cmd::sequence([
  Cmd::log("saved configuration"),
  Cmd::err_log("warning: using default profile"),
])

#Runtime Options

ProgramOptions::default()
  .alternate_screen(true)
  .mouse(MouseButtonMotion)
  .bracketed_paste(true)
  .focus_events(true)
  .hide_cursor(true)
  .fps(30)
  .max_messages_per_frame(128)
  .resize_poll_millis(50)

• ProgramOptions::default() uses the alternate screen.
• ProgramOptions::inline() renders in the current terminal scrollback.
• .without_renderer() keeps subscriptions and commands running without drawing frames.
• .fps(n) limits repaint cadence when commands or subscriptions produce many messages.

app.run()
app.run_with_options(ProgramOptions::inline())
app.run_returning_model()
app.run_with_cancel_token(options, token)
app.run_with_timeout(options, 5000)
let result = app.run_with_timeout_result(options, 5000)

let token = CancelToken::new()
// pass token to the running program
token.cancel()

#Layout and Styling

let style = Style::default()
  .fg(Ansi(16))
  .bg(Ansi(250))
  .bold()
  .underline()

text(style~, "Ready")

vstack(
  gap=1,
  style=Style::default()
    .fg(Ansi(250))
    .padding(Edge::all(1))
    .border()
    .size(width=48, height=8),
)  [
  text(style=Style::default().bold(), "Build status"),
  text("All checks passed"),
]

• display_width(text) accounts for wide characters.
• fit_line(text, width) clips and pads a line.
• take_width(text, width) clips without padding.
• wrap_text(text, width) wraps by display width.

#Widgets

///|
using @widgets {
  keymap,
  progress,
  status_line,
  type TextInput,
  type TextInputMsg,
}

///|
fn initial_model() -> Model {
  { input: TextInput(placeholder="Search"), completed: 0, total: 4, }
}

///|
fn view(model : Model) -> Node {
  vstack  [
    model.input.view(width=model.width),
    progress(current=model.completed, total=model.total, width=model.width),
    keymap(
      bindings=[
        { keys: [Enter], help: "submit", },
        { keys: [Ctrl("c")], help: "quit", },
      ],
      width=model.width,
    ),
  ]
}

///|
fn update(_emit : Emit[Msg], msg : Msg, model : Model) -> (Cmd, Model) {
  match msg {
    KeyPressed(key) => {
      let input_msg : TextInputMsg = TextInputKey(key)
      (Cmd::none(), { ..model, input: model.input.update(input_msg), })
    }
    Submitted => (Cmd::none(), { ..model, saved: model.input.value, })
  }
}

#Keyboard and Mouse Input

• Printable characters.
• Control keys such as Ctrl("c").
• Alt keys such as Alt("x").
• Arrow/navigation/function keys.
• Shift/Ctrl/Alt modified arrow and navigation keys.
• Kitty keyboard protocol CSI ... u.
• Bracketed paste.
• SGR mouse events.
• Focus gained/lost events.

#Testing

///|
async test "counter increments" {
  let result = app().run_headless(
    events=[Key(Up), Key(Up)],
    options=HeadlessOptions::default().size({ width: 40, height: 10, }),
  )
  @debug.assert_eq(result.model.count, 2)
  @debug.assert_eq(result.frames.length() > 0, true)
}

let frame = Frame::from_node(view(model), { width: 80, height: 24 })
assert_true(frame.to_string().contains("Ready"))

scripts/runtime_lab_tmux_test.sh

#Examples

#examples/counter

• Model, Msg, update, view, and subscriptions.
• Direct key and resize subscriptions.
• Responsive layout.
• Basic foreground/background styling.

moon run --target native examples/counter

#examples/codex-cli

• Responsive transcript layout.
• Prompt editing with Textarea.
• Prompt history.
• Streaming command messages.
• Diff rendering inside a chat pane.
• Scroll behavior with PageUp/PageDown and mouse wheel.
• Foreground/background color styling.

moon run --target native examples/codex-cli
moon run --target native examples/codex-cli -- --snapshot

#examples/init-cli

• Multi-step form flow.
• TextInput, List, checkbox-like toggles, progress, and summary views.
• Delayed command scheduling.
• Responsive split-panel layout.

moon run --target native examples/init-cli
moon run --target native examples/init-cli -- --snapshot

#examples/runtime-lab

• Safe stdout/stderr output.
• Cmd::exec_process.
• Cmd::suspend.
• Delayed jobs and timeout races.
• Model-level cancellation patterns.
• FPS-limited rendering.
• Modified keyboard input.

moon run --target native examples/runtime-lab
moon run --target native examples/runtime-lab -- --snapshot
scripts/runtime_lab_tmux_test.sh

#Design Notes

• Keep app state in Model; do not store terminal renderer state there.
• Keep update as the top-level message router. For larger examples, split by domain using helpers such as update_key and update_scenario; avoid helpers whose only job is to hide command construction.
• Use subscriptions to translate raw terminal events into semantic messages.
• Use emit(msg) for message commands. Use Cmd::log, Cmd::suspend, and Cmd::exec_process for runtime side effects instead of manually writing to stdout or toggling raw mode.
• Build views from Node values and widgets. The renderer remains independent from higher-level widgets so future Rabbita integration can reuse the app model/update layer.

#Current Limitations

• Interactive startup is implemented for POSIX native terminals.
• Windows currently returns UnsupportedPlatform for raw interactive mode.
• The widget set is practical but intentionally smaller than Bubble Tea's full ecosystem. It covers common CLI workflows, but advanced widgets should be built as plain MoonBit structs around the same Model/Msg/update pattern.