ratatui-ruby
/ratatui-ruby
Pomaga tworzyć interfejsy terminalowe TUI w Ruby z ratatui-ruby: widgety, pętla zdarzeń, widoki inline i pełnoekranowe oraz architektura Tea MVU.
- Autor
- hoblin ↗
- Repozytorium
- claude-ruby-marketplace ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 07.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 8
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 07.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Pomaga tworzyć interfejsy terminalowe TUI w Ruby z ratatui-ruby: widgety, pętla zdarzeń, widoki inline i pełnoekranowe oraz architektura Tea MVU.
Wyzwalacze z opisu
Oryginalny opis (EN)
This skill should be used when the user asks to "create a TUI", "terminal interface", "terminal UI", "ratatui", "ratatui-ruby", "inline viewport", "full-screen terminal app", "terminal widgets", "tui.draw", "tui.poll_event", or mentions RatatuiRuby.run, managed loop, terminal rendering, Tea MVU, or building CLI applications with rich UI elements. Should also be used when editing RatatuiRuby application files, working with terminal widgets, or discussing TUI architecture patterns.
Jak działa
- Quick Reference
- Core Pattern
- Common Widgets
- Layout
- Event Handling
- Styling
- Testing
- Frameworks
- Best Practices
- Additional Resources
Podgląd SKILL.md
---
name: ratatui-ruby
description: >-
This skill should be used when the user asks to "create a TUI", "terminal
interface", "terminal UI", "ratatui", "ratatui-ruby", "inline viewport",
"full-screen terminal app", "terminal widgets", "tui.draw", "tui.poll_event",
or mentions RatatuiRuby.run, managed loop, terminal rendering, Tea MVU, or
building CLI applications with rich UI elements. Should also be used when
editing RatatuiRuby application files, working with terminal widgets, or
discussing TUI architecture patterns.
version: 1.2.2
---
# RatatuiRuby
This skill provides guidance for building terminal user interfaces with RatatuiRuby, a Ruby gem wrapping Rust's Ratatui library. Use for TUI development, terminal widgets, layout systems, event handling, and testing terminal applications.
## Quick Reference
### Minimal Application
```ruby
require "ratatui_ruby"
RatatuiRuby.run do |tui|
loop do
tui.draw do |frame|
widget = tui.paragraph(text: "Hello, TUI!", block: tui.block(title: "App"))
frame.render_widget(widget, frame.area)
end
case tui.poll_event
in {type: :key, code: "q"}
break
in {type: :key, code: "c", modifiers: ["ctrl"]}
break
else
# Continue
end
end
end
```
### Key Concepts
| Concept | Purpose |
|---------|---------|
| `RatatuiRuby.run` | Managed loop handling terminal setup/teardown |
| `tui.draw` | Render widgets each frame |
| `tui.poll_event` | Capture keyboard/mouse input |
| `frame.area` | Available rendering area (Rect) |
| `frame.render_widget` | Render stateless widgets |
| `frame.render_stateful_widget` | Render widgets with state (List, Table) |
### Two Operating Modes
| Mode | Use Case | Setup |
|------|----------|-------|
| **Full-Screen** | Complete TUI applications | `RatatuiRuby.run { }` (default) |
| **Inline Viewport** | Rich CLI moments (spinners, progress) | `RatatuiRuby.run(viewport: :inline, height: 5) { }` |
**Full-Screen**: Takes over terminal, alternate screen, restored on exit.
**Inline Viewport**: Preserves scrollback, fixed-height widget area, output remains visible after exit.
## Core Pattern
The managed loop pattern handles terminal lifecycle:
```ruby
RatatuiRuby.run do |tui|
loop do
# 1. Draw UI
tui.draw do |frame|
# Render widgets
end
# 2. Handle events
case tui.poll_event
in {type: :key, code: "q"}
break
end
end
end
```
## Common Widgets
| Widget | Factory | Purpose |
|--------|---------|---------|
| Paragraph | `tui.paragraph(text:)` | Text display |
| Block | `tui.block(title:, borders:)` | Borders, titles, padding |
| List | `tui.list(items:)` | Selectable item list |
| Table | `tui.table(rows:, widths:)` | Tabular data |
| Gauge | `tui.gauge(ratio:)` | Progress indication |
| Tabs | `tui.tabs(titles:)` | Tab navigation |
| Chart | `tui.chart(datasets:)` | Data visualization |
| Canvas | `tui.canvas { }` | Custom drawing |
| Scrollbar | `tui.scrollbar` | Scroll indication |
### Stateless vs Stateful Widgets
**Stateless** (Paragraph, Block, Gauge):
```ruby
widget = tui.paragraph(text: "Hello")
frame.render_widget(widget, frame.area)
```
**Stateful** (List, Table):
```ruby
# Create state once (outside draw loop)
list_state = tui.list_state(0)
# In draw block
list = tui.list(items: ["Item A", "Item B", "Item C"])
frame.render_stateful_widget(list, frame.area, list_state)
# Update state on input
list_state.select_next if event_down?
```
### Block Composition
Wrap widgets with Block for borders and titles:
```ruby
block = tui.block(
title: "Main",
titles: [
{content: "Help: q", position: :bottom, alignment: :right}
],
borders: [:all],
border_style: {fg: "cyan"}
)
paragraph = tui.paragraph(text: "Content", block:)
```
## Layout
Split areas using constraints:
```ruby
layout = tui.layout(
direction: :vertical,
constraints: [
tui.constraint(:percentage, 20), # Header: 20%
tui.constraint(:min, 0), # Body: remaining
tui.constraint(:length, 3) # Footer: 3 rows
]
)
chunks = layout.split(frame.area)
# chunks[0] -> header area
# chunks[1] -> body area
# chunks[2] -> footer area
```
### Constraint Types
| Type | Syntax | Behavior |
|------|--------|----------|
| Length | `tui.constraint(:length, 5)` | Fixed 5 rows/cols |
| Percentage | `tui.constraint(:percentage, 50)` | 50% of parent |
| Min | `tui.constraint(:min, 10)` | At least 10 |
| Max | `tui.constraint(:max, 20)` | At most 20 |
| Ratio | `tui.constraint(:ratio, 1, 3)` | 1/3 of space |
| Fill | `tui.constraint(:fill)` | Expand into excess |
## Event Handling
### Pattern Matching
```ruby
case tui.poll_event
in {type: :key, code: "q"}
break
in {type: :key, code: "j"} | {type: :key, code: "down"}
list_state.select_next
in {type: :key, code: "k"} | {type: :key, code: "up"}
list_state.select_previous
in {type: :key, code: "c", modifiers: ["ctrl"]}
break
in {type: :mouse, kind: "down", button: "left", x:, y:}
handle_click(x, y)
in {type: :resize}
# Terminal resized, next draw adapts
end
```
### Event Helper Methods
```ruby
event = tui.poll_event
break if event.ctrl_c?
list_state.select_next if event.down? || event.j?
```
## Styling
Hash-based syntax for colors and modifiers:
```ruby
tui.paragraph(
text: "Styled text",
style: {fg: "green", bold: true},
block: tui.block(border_style: {fg: "cyan"})
)
```
### Text Composition
```ruby
line = tui.line([
tui.span("Normal "),
tui.span("Bold", style: {bold: true}),
tui.span(" Red", style: {fg: "red"})
])
tui.paragraph(text: line)
```
### Color Options
- Named: `"red"`, `"green"`, `"cyan"`, `"white"`
- Hex: `"#FF5733"`
- Indexed: 0-255 palette
## Testing
```ruby
require "ratatui_ruby/test_helper"
class MyAppTest < Minitest::Test
include RatatuiRuby::TestHelper
def test_renders_greeting
with_test_terminal(80, 24) do
RatatuiRuby.draw do |frame|
widget = RatatuiRuby::Widgets::Paragraph.new(text: "Hello")
frame.render_widget(widget, frame.area)
end
assert_snapshots("greeting") # Creates/compares snapshots/greeting.txt
end
end
def test_keyboard_navigation
with_test_terminal do
inject_keys("j", "j", "k") # Down, down, up
# Assert state changes
end
end
end
```
## Frameworks
### Tea (MVU Architecture)
Functional, Elm-style architecture for predictable state:
```ruby
require "ratatui_ruby/tea"
class Counter
include RatatuiRuby::Tea::App
def init
[Model.new(count: 0), nil]
end
def view(model, tui)
tui.paragraph(text: "Count: #{model.count}")
end
def update(message, model)
case message
in {type: :key, code: "q"}
[model, RatatuiRuby::Tea::Command.exit]
in {type: :key, code: "j"}
[model.with(count: model.count + 1), nil]
else
[model, nil]
end
end
end
Counter.new.run
```
## Best Practices
### Do
- Use `RatatuiRuby.run` for managed terminal lifecycle
- Create state objects outside the draw loop
- Use pattern matching for event handling
- Use inline viewports for CLI "rich moments"
- Test with `RatatuiRuby::TestHelper`
### Don't
- Handle Ctrl+C manually (use `event.ctrl_c?` helper)
- Forget to break the loop (leads to CPU spin)
- Render widgets before poll_event (blocks input)
- Use full-screen for simple progress indicators
## Additional Resources
### Reference Files
For detailed API documentation and patterns:
- **`references/core-concepts.md`** - Managed loop, terminal lifecycle, inline vs full-screen
- **`references/widgets.md`** - Complete widget catalog, composition patterns
- **`references/layout.md`** - Constraints, directions, nested layouts
- **`references/events.md`** - Keyboard, mouse, event handling patterns
- **`references/styling.md`** - Colors, modifiers, text composition
- **`references/testing.md`** - TestHelper, snapshots, event injection
- **`references/frameworks.md`** - Tea MVU, Kit components
Pliki w paczce (8)
- SKILL.md 8 KB
- references/core-concepts.md 8 KB
- references/events.md 8 KB
- references/frameworks.md 11 KB
- references/layout.md 9 KB
- references/styling.md 5 KB
- references/testing.md 8 KB
- references/widgets.md 12 KB
Wersje
W bazie nie ma innych skilli o nazwie ratatui-ruby.
Migawka bazy z 13.11.2026 · wersja paczki 1b514b71b099 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100tui-screen
Tworzy ekrany, komponenty i widoki ratatui dla terminalowego UI agents-in-a-box, z paletą kolorów, wzorcami komponentów i listą kontrolną jakości. - 100ratatui-themes
Stosuje spójne motywy kolorystyczne w terminalowych interfejsach Rust z ratatui, przełącza motywy w czasie działania i dodaje kolory semantyczne błędów, ostrzeżeń i sukcesu. - 96tui-tests
Pisze testy dla interfejsów terminalowych TUI opartych na Ratatui w repozytorium GitButler. - 95tui-design
Projektuje, buduje, przeprojektowuje i debuguje interfejsy terminalowe TUI: układy, skróty klawiszowe, znaki Unicode i testy. - 100tui-design
Pomaga projektować interfejsy terminalowe: układ paneli, paletę kolorów, nawigację klawiaturą i dashboardy w Ratatui, Ink, Textual czy Bubbletea. - 100tui-design
Projektuje i przegląda interfejsy terminalowe: pełnoekranowe TUI, interaktywne monity i narzędzia CLI wraz z ich zachowaniem.