ratatui_ruby 0.1.0 → 0.3.0

data/{docs → doc}/index.md

@@ -14,5 +14,5 @@
 
 ## Documentation for Contributors
 
-- [Contributing Guidelines](../CONTRIBUTING.md)
+- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md)
 - [More Documentation for Contributors](./contributors/index.md)

data/{docs → doc}/quickstart.md

@@ -11,7 +11,7 @@ Welcome to **ratatui_ruby**! This guide will help you get up and running with yo
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'ratatui_ruby'
+gem "ratatui_ruby"
 ```
 
 And then execute:
@@ -32,10 +32,10 @@ Here is a "Hello World" application that demonstrates the core lifecycle of a **
 
 ```ruby
 require "ratatui_ruby"
-
+ 
 # 1. Initialize the terminal
 RatatuiRuby.init_terminal
-
+ 
 begin
   # The Main Loop
   loop do
@@ -43,17 +43,17 @@ begin
     # We define a Paragraph widget inside a Block with a title and borders.
     view = RatatuiRuby::Paragraph.new(
       text: "Hello, Ratatui! Press 'q' to quit.",
+      align: :center,
       block: RatatuiRuby::Block.new(
-        title: "My First App",
+        title: "My Ruby TUI App",
         borders: [:all],
-        border_style: "cyan"
-      ),
-      alignment: :center
+        border_color: "cyan"
+      )
     )
-
+ 
     # 3. Draw the UI
     RatatuiRuby.draw(view)
-
+ 
     # 4. Poll for events
     event = RatatuiRuby.poll_event
     if event && event[:type] == :key && event[:code] == "q"
@@ -66,6 +66,8 @@ ensure
 end
 ```
 
+![Basic Application Screenshot](./images/examples-quickstart_lifecycle.rb.png)
+
 ### How it works
 
 1.  **`RatatuiRuby.init_terminal`**: Enters raw mode and switches to the alternate screen.
@@ -73,7 +75,42 @@ end
 3.  **`RatatuiRuby.draw(view)`**: The Ruby UI tree is passed to the Rust backend, which renders it to the terminal.
 4.  **`RatatuiRuby.poll_event`**: Checks for keyboard, mouse, or resize events.
 5.  **`RatatuiRuby.restore_terminal`**: Crucial for leaving raw mode and returning the user to their shell properly. Always wrap your loop in a `begin...ensure` block to guarantee this runs.
-6.  **`sleep 0.05`**: In a real app, you'd want to control your frame rate to avoid consuming 100% CPU.
+
+### DSL
+
+A small DSL is provided for convenience when writing scripts.
+
+```rb
+require "ratatui_ruby"
+
+# 1. Initialize the terminal, start the main loop, and ensure the terminal is restored.
+RatatuiRuby.main_loop do |tui|
+  # 2. Create your UI with methods instead of classes.
+  view = tui.paragraph(
+    text: "Hello, Ratatui! Press 'q' to quit.",
+    align: :center,
+    block: tui.block(
+      title: "My Ruby TUI App",
+      borders: [:all],
+      border_color: "cyan"
+    )
+  )
+
+  # 3. Use RatatuiRuby methods, too.
+  tui.draw(view)
+  event = tui.poll_event
+  
+  if event && event[:type] == :key && event[:code] == "q"
+    break
+  end
+end
+```
+
+#### How it works
+
+1.  **`RatatuiRuby.main_loop`**: This helper method manages the entire terminal lifecycle for you. It initializes the terminal before the block starts and ensures `restore_terminal` is called when the block exits (even if an error occurs).
+2.  **Widget Shorthand**: The block yields a special DSL object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Paragraph.new(...)`.
+3.  **Method SHorthand**: The DSL object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby::draw(...)`.
 
 ## Examples
 
@@ -89,11 +126,29 @@ A simple demonstration of `Block` and `Paragraph` widgets, reacting to arrow key
 
 ![Box Demo Screenshot](./images/examples-box_demo.rb.png)
 
+### [Calendar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/calendar_demo.rb)
+A simple demo application for the `Calendar` widget.
+
+![Calendar Screenshot](./images/examples-calendar_demo.rb.png)
+
+### [Chart Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/chart_demo.rb)
+Demonstrates the `Chart` widget with both scatter and line datasets, including custom axes.
+
+![Chart Screenshot](./images/examples-chart_demo.rb.png)
+
+### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/custom_widget.rb)
+Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
+
+![Custom Widget Screenshot](./images/examples-custom_widget.rb.png)
+
 ### [Dashboard](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/dashboard.rb)
 Uses `Layout`, `List`, and `Paragraph` to create a classic sidebar-and-content interface.
 
 ![Dashboard Screenshot](./images/examples-dashboard.rb.png)
 
+### [List Styles](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/list_styles.rb)
+Showcases advanced styling options for the `List` widget, including selection highlighting.
+
 ### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/login_form.rb)
 Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form with text input.
 
@@ -109,13 +164,23 @@ Detailed plumbing of mouse events, including clicks, drags, and movement trackin
 
 ![Mouse Events Screenshot](./images/examples-mouse_events.rb.png)
 
+### [Popup Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/popup_demo.rb)
+Demonstrates the `Clear` widget and how to prevent "style bleed" when rendering opaque popups over colored backgrounds.
+
+![Popup Demo Screenshot](./images/examples-popup_demo.rb.gif)
+
 ### [Scrollbar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scrollbar_demo.rb)
 A simple example of integrating the `Scrollbar` widget and handling mouse wheel events for scrolling.
 
 ![Scrollbar Demo Screenshot](./images/examples-scrollbar_demo.rb.png)
 
+### [Scroll Text](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scroll_text.rb)
+Demonstrates the `Paragraph` widget's scroll functionality, allowing navigation through long text content using arrow keys for both horizontal and vertical scrolling.
+
+![Scroll Text Screenshot](./images/examples-scroll_text.rb.png)
+
 ### [Stock Ticker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/stock_ticker.rb)
-Utilizes `Sparkline` and `LineChart` widgets to visualize real-time (simulated) data.
+Utilizes `Sparkline` and `Chart` widgets to visualize real-time (simulated) data.
 
 ![Stock Ticker Screenshot](./images/examples-stock_ticker.rb.png)
 
@@ -124,3 +189,8 @@ Combines `Table` and `Gauge` widgets in a vertical layout to create a functional
 
 ![System Monitor Screenshot](./images/examples-system_monitor.rb.png)
 
+### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/table_select.rb)
+Demonstrates interactive row selection in the `Table` widget with keyboard navigation, highlighting selected rows with custom styles and symbols.
+
+![Table Select Screenshot](./images/examples-table_select.rb.png)
+

data/examples/analytics.rb

@@ -3,7 +3,8 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-require_relative "../lib/ratatui_ruby"
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
 
 # Analytics Dashboard Example
 # Demonstrates Tabs and BarChart widgets.

data/examples/calendar_demo.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
+
+# A demo application for the Calendar widget.
+module CalendarDemo
+  def self.run
+    RatatuiRuby.init_terminal
+
+    loop do
+      now = Time.now
+      calendar = RatatuiRuby::Calendar.new(
+        year: now.year,
+        month: now.month,
+        header_style: RatatuiRuby::Style.new(fg: "yellow", modifiers: [:bold]),
+        block: RatatuiRuby::Block.new(title: " Calendar (q = quit) ", borders: [:all])
+      )
+
+      # Constrain the calendar to 24x10 characters
+      view = RatatuiRuby::Layout.new(
+        direction: :vertical,
+        constraints: [
+          RatatuiRuby::Constraint.length(10),
+          RatatuiRuby::Constraint.min(0),
+        ],
+        children: [
+          RatatuiRuby::Layout.new(
+            direction: :horizontal,
+            constraints: [
+              RatatuiRuby::Constraint.length(24),
+              RatatuiRuby::Constraint.min(0),
+            ],
+            children: [calendar, nil],
+          ),
+          nil,
+        ],
+      )
+
+      RatatuiRuby.draw(view)
+
+      event = RatatuiRuby.poll_event
+      break if event && event[:type] == :key && event[:code] == "q"
+
+      sleep 0.1
+    end
+  ensure
+    RatatuiRuby.restore_terminal
+  end
+end
+
+CalendarDemo.run if __FILE__ == $PROGRAM_NAME

data/examples/chart_demo.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
+
+# Chart Demo
+# Demonstrates Scatter and Line datasets in a single Chart.
+class ChartDemoApp
+  def run
+    RatatuiRuby.init_terminal
+    begin
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.1
+      end
+    ensure
+      RatatuiRuby.restore_terminal
+    end
+  end
+
+  def render
+    # Scatter data: Random points
+    scatter_data = Array.new(20) { [rand(0.0..10.0), rand(-1.0..1.0)] }
+
+    # Line data: Sine wave
+    line_data = (0..100).map do |i|
+      x = i / 10.0
+      [x, Math.sin(x)]
+    end
+
+    datasets = [
+      RatatuiRuby::Dataset.new(
+        name: "Scatter",
+        data: scatter_data,
+        color: "red",
+        marker: :dot,
+        graph_type: :scatter,
+      ),
+      RatatuiRuby::Dataset.new(
+        name: "Line",
+        data: line_data,
+        color: "green",
+        marker: :braille,
+        graph_type: :line,
+      ),
+    ]
+
+    chart = RatatuiRuby::Chart.new(
+      datasets:,
+      x_axis: RatatuiRuby::Axis.new(
+        title: "Time",
+        bounds: [0.0, 10.0],
+        labels: %w[0 5 10],
+        style: RatatuiRuby::Style.new(fg: :yellow),
+      ),
+      y_axis: RatatuiRuby::Axis.new(
+        title: "Amplitude",
+        bounds: [-1.0, 1.0],
+        labels: %w[-1 0 1],
+        style: RatatuiRuby::Style.new(fg: :cyan),
+      ),
+      block: RatatuiRuby::Block.new(
+        title: "Chart Demo (Q to quit)",
+        borders: [:all],
+      ),
+    )
+
+    RatatuiRuby.draw(chart)
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    return nil unless event
+
+    return :quit if event[:type] == :key && event[:code] == "q"
+    nil
+  end
+end
+
+ChartDemoApp.new.run if __FILE__ == $PROGRAM_NAME

data/examples/custom_widget.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
+
+# A custom widget that draws a diagonal line.
+class DiagonalWidget
+  def render(area, buffer)
+    # Draw a diagonal line within the area
+    (0..10).each do |i|
+      next if area.x + i >= area.x + area.width || area.y + i >= area.y + area.height
+
+      buffer.set_string(
+        area.x + i,
+        area.y + i,
+        "\\",
+        RatatuiRuby::Style.new(fg: :red, modifiers: [:bold])
+      )
+    end
+  end
+end
+
+RatatuiRuby.main_loop do |tui|
+  tui.draw(
+    RatatuiRuby::Layout.new(
+      direction: :vertical,
+      constraints: [
+        RatatuiRuby::Constraint.percentage(50),
+        RatatuiRuby::Constraint.percentage(50),
+      ],
+      children: [
+        RatatuiRuby::Paragraph.new(text: "Above custom widget"),
+        DiagonalWidget.new,
+      ]
+    )
+  )
+
+  event = RatatuiRuby.poll_event
+  break if event && event[:type] == :key && event[:code] == "q"
+end

data/examples/list_styles.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
+
+# Styled List Example
+# Demonstrates advanced styling options for the List widget.
+class ListStylesApp
+  attr_reader :selected_index
+
+  def initialize
+    @items = ["Item 1", "Item 2", "Item 3"]
+    @selected_index = 0
+  end
+
+  def run
+    RatatuiRuby.init_terminal
+    begin
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    ensure
+      RatatuiRuby.restore_terminal
+    end
+  end
+
+  def render
+    RatatuiRuby.draw(
+      RatatuiRuby::List.new(
+        items: @items,
+        selected_index: @selected_index,
+        style: RatatuiRuby::Style.new(fg: :white, bg: :black),
+        highlight_style: RatatuiRuby::Style.new(fg: :blue, bg: :white, modifiers: [:bold]),
+        highlight_symbol: ">> ",
+        block: RatatuiRuby::Block.new(
+          title: "Styled List (Up/Down to move, Q to quit)",
+          borders: [:all]
+        )
+      )
+    )
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    return nil unless event
+
+    if event[:type] == :key
+      case event[:code]
+      when "up"
+        @selected_index = (@selected_index - 1) % @items.size
+      when "down"
+        @selected_index = (@selected_index + 1) % @items.size
+      when "q"
+        return :quit
+      end
+    end
+    nil
+  end
+end
+
+ListStylesApp.new.run if __FILE__ == $PROGRAM_NAME

data/examples/login_form.rb

@@ -3,7 +3,8 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-require_relative "../lib/ratatui_ruby"
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
 
 class LoginFormApp
   PREFIX = "Enter Username: [ "

data/examples/popup_demo.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
+
+# Popup Demo Example
+# Demonstrates the Clear widget for creating opaque popups.
+
+class PopupDemo
+  def initialize
+    @clear_enabled = false
+  end
+
+  def run
+    RatatuiRuby.init_terminal
+    begin
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    ensure
+      RatatuiRuby.restore_terminal
+    end
+  end
+
+  def render
+    # 1. Background: Loud Red Background
+    # This demonstrates "Style Bleed" where the background color persists
+    # unless explicitly cleared or overwritten.
+    background = RatatuiRuby::Paragraph.new(
+      text: "BACKGROUND RED " * 100,
+      style: RatatuiRuby::Style.new(bg: :red, fg: :white),
+      wrap: true
+    )
+
+    # 2. Popup Content: No specific background set (Style.default)
+    # Without Clear, this will "inherit" the red background from underneath.
+    popup_text = if @clear_enabled
+                   "✓ Clear is ENABLED\n\nResets background to default\n(Usually Black/Transparent)\n\nPress Space to toggle"
+                 else
+                   "✗ Clear is DISABLED\n\nStyle Bleed: Popup is RED!\n(Inherits background style)\n\nPress Space to toggle"
+                 end
+
+    popup_content = RatatuiRuby::Paragraph.new(
+      text: popup_text,
+      align: :center,
+      block: RatatuiRuby::Block.new(
+        title: "Popup Demo (Press 'q' to quit)",
+        borders: [:all]
+      )
+    )
+
+    # Build the UI with or without Clear
+    if @clear_enabled
+      # With Clear: Resets the style in the popup area before rendering content
+      ui = RatatuiRuby::Overlay.new(
+        layers: [
+          background,
+          RatatuiRuby::Center.new(
+            child: RatatuiRuby::Overlay.new(
+              layers: [
+                RatatuiRuby::Clear.new,
+                popup_content
+              ]
+            ),
+            width_percent: 60,
+            height_percent: 50
+          )
+        ]
+      )
+    else
+      # Without Clear: Background style (RED) bleeds through the popup
+      ui = RatatuiRuby::Overlay.new(
+        layers: [
+          background,
+          RatatuiRuby::Center.new(
+            child: popup_content,
+            width_percent: 60,
+            height_percent: 50
+          )
+        ]
+      )
+    end
+
+    RatatuiRuby.draw(ui)
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    if event
+      case event[:code]
+      when "q"
+        :quit
+      when " "
+        @clear_enabled = !@clear_enabled
+      end
+    end
+  end
+end
+
+PopupDemo.new.run if __FILE__ == $0

data/examples/quickstart_dsl.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "ratatui_ruby"
+
+# 1. Initialize the terminal, start the main loop, and ensure the terminal is restored.
+RatatuiRuby.main_loop do |tui|
+  # 2. Create your UI with methods instead of classes.
+  view = tui.paragraph(
+    text: "Hello, Ratatui! Press 'q' to quit.",
+    align: :center,
+    block: tui.block(
+      title: "My Ruby TUI App",
+      borders: [:all],
+      border_color: "cyan"
+    )
+  )
+
+  # 3. Use RatatuiRuby methods, too.
+  tui.draw(view)
+  event = tui.poll_event
+
+  if event && event[:type] == :key && event[:code] == "q"
+    break
+  end
+end

data/examples/quickstart_lifecycle.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "ratatui_ruby"
+
+# 1. Initialize the terminal
+RatatuiRuby.init_terminal
+
+begin
+  # The Main Loop
+  loop do
+    # 2. Create your UI (Immediate Mode)
+    # We define a Paragraph widget inside a Block with a title and borders.
+    view = RatatuiRuby::Paragraph.new(
+      text: "Hello, Ratatui! Press 'q' to quit.",
+      align: :center,
+      block: RatatuiRuby::Block.new(
+        title: "My Ruby TUI App",
+        borders: [:all],
+        border_color: "cyan"
+      )
+    )
+
+    # 3. Draw the UI
+    RatatuiRuby.draw(view)
+
+    # 4. Poll for events
+    event = RatatuiRuby.poll_event
+    if event && event[:type] == :key && event[:code] == "q"
+      break
+    end
+  end
+ensure
+  # 5. Restore the terminal to its original state
+  RatatuiRuby.restore_terminal
+end

data/examples/readme_usage.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "ratatui_ruby"
+RatatuiRuby.main_loop do |tui|
+  tui.draw \
+    tui.paragraph \
+      text: "Hello, Ratatui! Press 'q' to quit.",
+      align: :center,
+      block: tui.block(
+        title: "My Ruby TUI App",
+        borders: [:all],
+        border_color: "cyan"
+      )
+  event = tui.poll_event
+  break if event && event[:type] == :key && event[:code] == "q"
+end