Migrating to v0.7.0

v0.7.0 restructures the library to align with upstream Ratatui. For most users, this is a non-breaking change. For some, it is breaking.

Are You Affected?

If your code looks like this, you’re fine:

RatatuiRuby.run do |tui|
  tui.draw tui.paragraph(text: "Hello", block: tui.block(title: "Title"))
  event = tui.poll_event
end

The TUI API method names are unchanged. Your application works without modification.

If your code uses highlight_style: on Tables, rename it:

# Before (v0.6.0)
tui.table(rows: [...], highlight_style: tui.style(fg: :yellow))

# After (v0.7.0)
tui.table(rows: [...], row_highlight_style: tui.style(fg: :yellow))

This change aligns with Ratatui’s API naming convention.

If your code instantiates classes directly, you have work to do:

# These lines break in v0.7.0
paragraph = RatatuiRuby::Paragraph.new(text: "Hello")
style = RatatuiRuby::Style.new(fg: :red)
rect = RatatuiRuby::Rect.new(x: 0, y: 0, width: 10, height: 5)

The old flat namespace no longer exists. Classes moved into modules.

Option 1: Use the TUI API (Recommended)

Switch to the TUI API. It hides namespace verbosity and provides IDE autocomplete.

RatatuiRuby.run do |tui|
  # All these work exactly as before
  paragraph = tui.paragraph(text: "Hello")
  style = tui.style(fg: :red)
  rect = tui.rect(x: 0, y: 0, width: 10, height: 5)
  constraint = tui.constraint_length(20)
  
  # New in v0.7.0
  cell = tui.table_cell(content: "Error", style: tui.style(bg: :red))
  row = tui.table_row(cells: ["A", "B", "C"], style: tui.style(bg: :dark_gray))
end

Option 2: Update to New Namespaces

If you prefer direct class instantiation, update to the new paths:

Bulk Migration

find . -name "*.rb" -exec sed -i '' \
  's/RatatuiRuby::Rect/RatatuiRuby::Layout::Rect/g; \
   s/RatatuiRuby::Constraint\./RatatuiRuby::Layout::Constraint./g; \
   s/RatatuiRuby::Paragraph\.new/RatatuiRuby::Widgets::Paragraph.new/g; \
   s/RatatuiRuby::Block\.new/RatatuiRuby::Widgets::Block.new/g; \
   s/RatatuiRuby::List\.new/RatatuiRuby::Widgets::List.new/g; \
   s/RatatuiRuby::Table\.new/RatatuiRuby::Widgets::Table.new/g; \
   s/RatatuiRuby::Style\.new/RatatuiRuby::Style::Style.new/g; \
   s/RatatuiRuby::Session/RatatuiRuby::TUI/g; \
   s/highlight_style:/row_highlight_style:/g' {} \;

Session → TUI Rename

The Session class is now TUI. If you reference it directly:

# Before
tui = RatatuiRuby::Session.new

# After
tui = RatatuiRuby::TUI.new

Most users never reference the class directly. The |tui| block parameter works unchanged.

Table: highlight_style → row_highlight_style

The highlight_style: parameter on Table is now row_highlight_style:. This aligns with Ratatui’s naming convention where row_highlight_style, column_highlight_style, and cell_highlight_style form a consistent trio.

# Before (v0.6.0)
tui.table(
  rows: data,
  highlight_style: tui.style(fg: :yellow)
)

# After (v0.7.0)
tui.table(
  rows: data,
  row_highlight_style: tui.style(fg: :yellow)
)

Text::Line style Field

Text::Line now accepts a style: parameter for line-level styling. This matches Ratatui’s Line struct.

# New in v0.7.0: Line-level styling
line = tui.text_line(
  spans: [tui.text_span(content: "Hello")],
  style: tui.style(bg: :dark_gray)  # Applied to entire line
)

Existing code without style: continues to work unchanged.

New Table Cell and Row Classes

v0.7.0 adds Widgets::Cell and Widgets::Row for table construction with per-cell styling:

table = tui.table(
  rows: [
    tui.table_row(
      cells: [
        tui.table_cell(content: "Name", style: tui.style(fg: :blue)),
        "Value"
      ],
      style: tui.style(bg: :dark_gray)
    )
  ],
  widths: [tui.constraint_length(20), tui.constraint_fill]
)

Buffer::Cell vs Widgets::Cell

Two Cell classes now exist:

• Buffer::Cell — Terminal cell for inspection (returned by get_cell_at)

• Widgets::Cell — Table cell for construction (content + style wrapper)

# Buffer inspection (unchanged)
cell = RatatuiRuby.get_cell_at(0, 0)  # Returns Buffer::Cell
cell.char  # => "X"
cell.fg    # => :red

# Table cell construction (new)
cell = tui.table_cell(content: "Error", style: tui.style(bg: :red))

Why This Change?

The old flat namespace caused name collisions (Cell for buffers vs. tables) and diverged from Ratatui’s module structure. The new hierarchy:

• Maps 1:1 to Ratatui documentation

• Prevents future collisions

• Enables IDE autocomplete via explicit TUI methods

For LLMs

Copy the following prompt to your AI assistant to help migrate your ratatui_ruby application from v0.6.0 to v0.7.0.

“‘markdown I'm migrating a Ruby TUI application from ratatui_ruby` v0.6.0 to v0.7.0. The library restructured its namespaces. Apply these transformations:

Namespace Changes: - RatatuiRuby::Rect → RatatuiRuby::Layout::Rect - RatatuiRuby::Constraint → RatatuiRuby::Layout::Constraint - RatatuiRuby::Layout → RatatuiRuby::Layout::Layout - RatatuiRuby::Style → RatatuiRuby::Style::Style - RatatuiRuby::Paragraph → RatatuiRuby::Widgets::Paragraph - RatatuiRuby::Block → RatatuiRuby::Widgets::Block - RatatuiRuby::Table → RatatuiRuby::Widgets::Table - RatatuiRuby::List → RatatuiRuby::Widgets::List - RatatuiRuby::Cell → RatatuiRuby::Buffer::Cell - All other widgets: RatatuiRuby::X → RatatuiRuby::Widgets::X

Class Rename: - RatatuiRuby::Session → RatatuiRuby::TUI

Parameter Rename: - Table highlight_style: → row_highlight_style:

Preferred Approach: Convert direct class instantiation to TUI API:

# Instead of:
RatatuiRuby::Widgets::Paragraph.new(text: "Hello")

# Use:
tui.paragraph(text: "Hello")

TUI API method names are unchanged. Code using tui.paragraph(...), tui.block(...), tui.style(...) etc. works without modification.

Cell Disambiguation: - Buffer::Cell — Terminal cell for inspection (returned by get_cell_at) - Widgets::Cell — Table cell for construction (use tui.table_cell) - The old RatatuiRuby::Cell is now RatatuiRuby::Buffer::Cell

New in v0.7.0: - tui.table_cell(content:, style:) — styled table cells - tui.table_row(cells:, style:, height:) — styled table rows - Text::Line now accepts style: parameter

Please update my code following these rules. ““