ratatui_ruby 0.5.0 → 0.7.0

data/examples/widget_barchart_demo/app.rb

@@ -23,11 +23,11 @@ require "ratatui_ruby"
 # rdoc-image:/doc/images/widget_barchart_demo.png
 class WidgetBarchartDemo
   def initialize
-    @data_index = 0
+    @data_index = 2
     @styles = nil # Initialized in run
-    @style_index = 0
-    @label_style_index = 0
-    @value_style_index = 0
+    @style_index = 3
+    @label_style_index = 3
+    @value_style_index = 3
     @bar_sets = [
       { name: "Default", set: nil },
       { name: "Numbers (Short)", set: { 8 => "8", 7 => "7", 6 => "6", 5 => "5", 4 => "4", 3 => "3", 2 => "2", 1 => "1", 0 => "0" } },
@@ -38,7 +38,7 @@ class WidgetBarchartDemo
     @direction = :vertical
     @bar_width = 8
     @bar_gap = 1
-    @group_gap = 0
+    @group_gap = 2
     @height_mode = :full
     @hotkey_style = nil
   end

data/examples/widget_block_demo/README.md

@@ -0,0 +1,36 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Block Widget Demo
+
+[![Block Demo](../../doc/images/widget_block_demo.png)](app.rb)
+
+This example demonstrates the versatile `Block` widget, which provides the visual container, borders, and titles for almost every other widget in `ratatui_ruby`.
+
+## Key Concepts
+
+- **Borders:** Choose which sides to show and apply different border types (plain, rounded, double, thick, etc.).
+- **Titles:** Add a main title with alignment or multiple titles at the top and bottom with independent styles and positions.
+- **Padding:** Define inner spacing using uniform or directional (L/R/T/B) values.
+- **Styling:** Individually style the block's content area, its borders, and its titles.
+- **Custom Border Sets:** Create entirely custom border appearances by defining each character in the border set.
+
+## Hotkeys
+
+- `t`: Cycle **Title** (None, Main Title)
+- `a`: Cycle **Title Alignment** (Left, Center, Right)
+- `s`: Cycle **Title Style** (None, Cyan Bold, Yellow Italic)
+- `e`: Cycle **Additional Titles** (None, Top+Bottom, Complex)
+- `b`: Cycle **Borders** (All, Top/Bottom, Left/Right, None)
+- `y`: Cycle **Border Type** (Rounded, Plain, Double, Thick, Quadrant, Custom)
+- `c`: Cycle **Border Style** (Magenta Bold, None, Green, Blue on White)
+- `p`: Cycle **Padding** (Uniform, None, Directional, Narrow)
+- `f`: Cycle **Base Style** (Dark Gray, None, White on Black)
+- `q`: **Quit**
+
+## Usage
+
+```bash
+ruby examples/widget_block_demo/app.rb
+```

data/examples/widget_block_demo/app.rb

@@ -0,0 +1,256 @@
+# 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"
+
+# Demonstrates the Block widget with interactive attribute cycling.
+#
+# Blocks are the foundation of terminal layouts, providing structure, borders, and titles.
+# This demo showcases all available parameters, including advanced title positioning,
+# directional padding, and custom border sets.
+#
+# === Examples
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_block_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_block_demo.png
+class WidgetBlockDemo
+  def initialize
+    @title_configs = [
+      { name: "None", title: nil },
+      { name: "Main Title", title: "Main Title" },
+    ]
+    @title_index = 1
+
+    @titles_configs = [
+      { name: "None", titles: [] },
+      {
+name: "Top + Bottom",
+titles: [
+  { content: "Top Right", alignment: :right, position: :top },
+  { content: "Bottom Left", alignment: :left, position: :bottom },
+      ],
+},
+      {
+name: "Complex",
+titles: [
+  { content: "★ Left ★", alignment: :left, position: :top },
+  { content: "Center", alignment: :center, position: :top },
+  { content: "Right", alignment: :right, position: :top },
+  { content: "Bottom Center", alignment: :center, position: :bottom },
+      ],
+},
+    ]
+    @titles_index = 1
+
+    @alignment_configs = [
+      { name: "Left", alignment: :left },
+      { name: "Center", alignment: :center },
+      { name: "Right", alignment: :right },
+    ]
+    @alignment_index = 1 # Center
+
+    @border_configs = [
+      { name: "All", borders: [:all] },
+      { name: "Top/Bottom", borders: [:top, :bottom] },
+      { name: "Left/Right", borders: [:left, :right] },
+      { name: "None", borders: [] },
+    ]
+    @border_index = 0
+
+    @border_type_configs = [
+      { name: "Rounded", type: :rounded },
+      { name: "Plain", type: :plain },
+      { name: "Double", type: :double },
+      { name: "Thick", type: :thick },
+      { name: "Quadrant Inside", type: :quadrant_inside },
+      { name: "Quadrant Outside", type: :quadrant_outside },
+      {
+name: "Custom Set",
+type: nil,
+set: {
+        top_left: "1",
+        top_right: "2",
+        bottom_left: "3",
+        bottom_right: "4",
+        vertical_left: "5",
+        vertical_right: "6",
+        horizontal_top: "7",
+        horizontal_bottom: "8",
+      },
+},
+    ]
+    @border_type_index = 0
+
+    @padding_configs = [
+      { name: "Uniform (2)", padding: 2 },
+      { name: "None (0)", padding: 0 },
+      { name: "Directional (L:4, T:2)", padding: [4, 0, 2, 0] },
+      { name: "Narrow (H:1, V:0)", padding: [1, 1, 0, 0] },
+    ]
+    @padding_index = 0
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+
+      @title_styles = [
+        { name: "None", style: nil },
+        { name: "Magenta Bold", style: @tui.style(fg: :magenta, modifiers: [:bold]) },
+        { name: "Cyan Bold", style: @tui.style(fg: :cyan, modifiers: [:bold]) },
+        { name: "Yellow Italic", style: @tui.style(fg: :yellow, modifiers: [:italic]) },
+      ]
+      @title_style_index = 1 # Magenta Bold
+
+      @border_styles = [
+        { name: "Cyan", style: @tui.style(fg: :cyan) },
+        { name: "Magenta Bold", style: @tui.style(fg: :magenta, modifiers: [:bold]) },
+        { name: "None", style: nil },
+        { name: "Blue on White", style: @tui.style(fg: :blue, bg: :white) },
+      ]
+      @border_style_index = 0
+
+      @base_styles = [
+        { name: "Dark Gray", style: @tui.style(fg: :dark_gray) },
+        { name: "None", style: nil },
+        { name: "White on Black", style: @tui.style(fg: :white, bg: :black) },
+      ]
+      @base_style_index = 1
+
+      @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render
+    title_config = @title_configs[@title_index]
+    titles_config = @titles_configs[@titles_index]
+    alignment_config = @alignment_configs[@alignment_index]
+    title_style_config = @title_styles[@title_style_index]
+    border_config = @border_configs[@border_index]
+    border_type_config = @border_type_configs[@border_type_index]
+    border_style_config = @border_styles[@border_style_index]
+    base_style_config = @base_styles[@base_style_index]
+    padding_config = @padding_configs[@padding_index]
+
+    @tui.draw do |frame|
+      main_area, control_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(10),
+        ]
+      )
+
+      # Render the demo block
+      demo_block = @tui.block(
+        title: title_config[:title],
+        titles: titles_config[:titles],
+        title_alignment: alignment_config[:alignment],
+        title_style: title_style_config[:style],
+        borders: border_config[:borders],
+        border_type: border_type_config[:type],
+        border_set: border_type_config[:set],
+        border_style: border_style_config[:style],
+        style: base_style_config[:style],
+        padding: padding_config[:padding]
+      )
+
+      # Paragraph inside the block to show padding/content interaction
+      content = @tui.paragraph(
+        text: "This paragraph is rendered inside the Block widget.\n" \
+          "You can see how padding and base style affect this content.\n\n" \
+          "Current State:\n" \
+          "• Padding: #{padding_config[:name]}\n" \
+          "• Borders: #{border_config[:name]}\n" \
+          "• Type: #{border_type_config[:name]}",
+        block: demo_block
+      )
+      frame.render_widget(content, main_area)
+
+      # Render control panel
+      control_panel = @tui.block(
+        title: "Controls",
+        borders: [:all],
+        children: [
+          @tui.paragraph(
+            text: [
+              @tui.text_line(spans: [
+                @tui.text_span(content: "t", style: @hotkey_style),
+                @tui.text_span(content: ": Title (#{title_config[:name]})  "),
+                @tui.text_span(content: "a", style: @hotkey_style),
+                @tui.text_span(content: ": Alignment (#{alignment_config[:name]})  "),
+                @tui.text_span(content: "s", style: @hotkey_style),
+                @tui.text_span(content: ": Title Style (#{title_style_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "e", style: @hotkey_style),
+                @tui.text_span(content: ": Additional Titles (#{titles_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "b", style: @hotkey_style),
+                @tui.text_span(content: ": Borders (#{border_config[:name]})  "),
+                @tui.text_span(content: "y", style: @hotkey_style),
+                @tui.text_span(content: ": Border Type (#{border_type_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "c", style: @hotkey_style),
+                @tui.text_span(content: ": Border Style (#{border_style_config[:name]})  "),
+                @tui.text_span(content: "p", style: @hotkey_style),
+                @tui.text_span(content: ": Padding (#{padding_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "f", style: @hotkey_style),
+                @tui.text_span(content: ": Base Style (#{base_style_config[:name]})  "),
+                @tui.text_span(content: "q", style: @hotkey_style),
+                @tui.text_span(content: ": Quit"),
+              ]),
+            ]
+          ),
+        ]
+      )
+      frame.render_widget(control_panel, control_area)
+    end
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "t"
+      @title_index = (@title_index + 1) % @title_configs.size
+    in type: :key, code: "e"
+      @titles_index = (@titles_index + 1) % @titles_configs.size
+    in type: :key, code: "a"
+      @alignment_index = (@alignment_index + 1) % @alignment_configs.size
+    in type: :key, code: "s"
+      @title_style_index = (@title_style_index + 1) % @title_styles.size
+    in type: :key, code: "b"
+      @border_index = (@border_index + 1) % @border_configs.size
+    in type: :key, code: "y"
+      @border_type_index = (@border_type_index + 1) % @border_type_configs.size
+    in type: :key, code: "c"
+      @border_style_index = (@border_style_index + 1) % @border_styles.size
+    in type: :key, code: "p"
+      @padding_index = (@padding_index + 1) % @padding_configs.size
+    in type: :key, code: "f"
+      @base_style_index = (@base_style_index + 1) % @base_styles.size
+    else
+      nil
+    end
+  end
+end
+
+WidgetBlockDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_box_demo/README.md

@@ -0,0 +1,45 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Box (Block) Widget Example
+
+[![widget_box_demo](../../doc/images/widget_box_demo.png)](app.rb)
+
+Demonstrates visual container attributes with interactive cycling.
+
+Widgets often float in a void. Without boundaries, interfaces become a chaotic mess of text. `Block` (often called a Box) provides the structure and visual hierarchy needed to organize information.
+
+## Features Demonstrated
+
+- **Border Types**: Native styles like `:plain`, `:rounded`, `:double`, `:thick`.
+- **Custom Borders**: defining completely custom character sets (e.g. using numbers or letters for borders).
+- **Styling**: Independent control over border color, background style, and title style.
+- **Positioning**: Placing titles on the `:top` or `:bottom` border (`position`).
+- **Alignment**: Aligning titles to `:left`, `:center`, or `:right` (`alignment`).
+
+## Hotkeys
+
+- **Arrow Keys**: Change Border/Content Color
+- **Space**: Cycle Border Type (`border_type`)
+- **c**: Cycle Custom Border Set (`border_set`)
+- **Enter**: Cycle Title Alignment (`title_alignment`)
+- **s**: Cycle Content Style (`style`)
+- **t**: Cycle Title Style (`title_style`)
+- **b**: Cycle Border Style (`border_style`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_box_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Group related widgets together.
+- Create distinct "panels" or "cards" in your UI.
+- Style borders to indicate state (e.g., Red border for error state).
+- Understand the difference between `style` (content) and `border_style` (frame).

data/examples/widget_calendar_demo/README.md

@@ -0,0 +1,39 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Calendar Widget Example
+
+[![widget_calendar_demo](../../doc/images/widget_calendar_demo.png)](app.rb)
+
+Demonstrates a monthly calendar with customizable headers and event highlighting.
+
+Rendering dates in a grid involves complex calculations for leap years and weekday offsets. This widget handles that logic, letting you focus on displaying dates.
+
+## Features Demonstrated
+
+- **Headers**: Toggling the Month name and Weekday labels.
+- **Surrounding Days**: displaying (or hiding/dimming) days from the previous and next months to fill the grid.
+- **Event Styling**: applying specific styles to individual `Time` or `Date` objects to highlight events.
+
+## Hotkeys
+
+- **h**: Toggle Month Header (`show_month_header`)
+- **w**: Toggle Weekday Labels (`show_weekdays_header`)
+- **s**: Toggle Surrounding Days (`show_surrounding`)
+- **e**: Toggle Example Events (`events`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_calendar_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Display a date picker.
+- Show a schedule or timeline view.
+- Highlight specific dates (deadlines, holidays) on a calendar grid.

data/examples/widget_calendar_demo/app.rb

@@ -23,6 +23,10 @@ require "ratatui_ruby"
 #
 # rdoc-image:/doc/images/widget_calendar_demo.png
 class WidgetCalendarDemo
+  def initialize(date: nil)
+    @date = date
+  end
+
   def run
     RatatuiRuby.run do |tui|
       show_header = true
@@ -32,7 +36,7 @@ class WidgetCalendarDemo
       hotkey_style = tui.style(modifiers: [:bold])
 
       loop do
-        now = Time.now
+        now = @date || Time.now
         surrounding_style = show_surrounding ? tui.style(fg: "gray", modifiers: [:dim]) : nil
 
         events_map = if show_events

data/examples/widget_canvas_demo/README.md

@@ -0,0 +1,27 @@
+# Canvas Widget Demo
+
+[![widget_canvas_demo](../../doc/images/widget_canvas_demo.png)](app.rb)
+
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+This example demonstrates the `Canvas` widget, which provides a high-resolution drawing surface using Braille characters.
+
+## Key Concepts
+
+- **Shapes**: Supports `Point`, `Line`, `Rectangle`, `Circle`, and `Map`.
+- **Coordinates**: Uses a float-based coordinate system independent of terminal cells.
+- **Markers**: Can use Braille (high res) or block characters (lower res) for rendering.
+
+## Controls
+
+| Key | Action |
+| --- | --- |
+| `q` | Quit |
+
+## Screenshot
+## Source Code
+
+- [app.rb](app.rb)

data/examples/widget_canvas_demo/app.rb

@@ -0,0 +1,123 @@
+# 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"
+
+# Demo: Canvas Widget
+# Demonstrates how to draw geometric shapes (Points, Lines, Rects, Circles)
+# on a high-resolution canvas.
+class WidgetCanvasDemo
+  def initialize
+    @x_offset = 0.0
+    @y_offset = 0.0
+    @time = 0.0
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        # Animate
+        @time += 0.1
+        @x_offset = Math.sin(@time) * 20.0
+        @y_offset = Math.cos(@time) * 20.0
+
+        render
+        break if handle_input == :quit
+
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render
+    @tui.draw do |frame|
+      # Define shapes
+      shapes = []
+
+      # 1. Static Grid (Lines)
+      (-100..100).step(20) do |i|
+        shapes << @tui.shape_line(x1: i.to_f, y1: -100.0, x2: i.to_f, y2: 100.0, color: :gray)
+        shapes << @tui.shape_line(x1: -100.0, y1: i.to_f, x2: 100.0, y2: i.to_f, color: :gray)
+      end
+
+      # 2. Moving Circle (The "Player")
+      shapes << @tui.shape_circle(
+        x: @x_offset,
+        y: @y_offset,
+        radius: 10.0,
+        color: :green
+      )
+
+      # 3. Static Rectangle (Target)
+      shapes << @tui.shape_rectangle(
+        x: 30.0,
+        y: 30.0,
+        width: 20.0,
+        height: 20.0,
+        color: :red
+      )
+
+      # 4. Points (Starfield)
+      # Deterministic "random" points
+      10.times do |i|
+        shapes << @tui.shape_point(
+          x: ((i * 37) % 200) - 100.0,
+          y: ((i * 19) % 200) - 100.0
+        )
+      end
+
+      # 5. Label
+      shapes << @tui.shape_line(x1: 0.0, y1: 0.0, x2: @x_offset, y2: @y_offset, color: :yellow)
+
+      canvas = @tui.canvas(
+        shapes:,
+        x_bounds: [-100.0, 100.0],
+        y_bounds: [-100.0, 100.0],
+        marker: :braille,
+        block: @tui.block(title: "Canvas Demo", borders: [:all])
+      )
+
+      # Main area for canvas
+      layout = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(3),
+        ]
+      )
+
+      frame.render_widget(canvas, layout[0])
+
+      # Controls
+      controls = @tui.paragraph(
+        text: [
+          @tui.text_line(spans: [
+            @tui.text_span(content: "Canvas auto-animates.", style: @tui.style(fg: :yellow)),
+          ]),
+          @tui.text_line(spans: [
+            @tui.text_span(content: "q", style: @tui.style(modifiers: [:bold, :underlined])),
+            @tui.text_span(content: ": Quit"),
+          ]),
+        ],
+        block: @tui.block(borders: [:top])
+      )
+      frame.render_widget(controls, layout[1])
+    end
+  end
+
+  def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    else
+      # Ignore other events
+    end
+  end
+end
+
+WidgetCanvasDemo.new.run if __FILE__ == $0

data/examples/widget_cell_demo/README.md

@@ -0,0 +1,36 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Cell Widget Example
+
+[![widget_cell_demo](../../doc/images/widget_cell_demo.png)](app.rb)
+
+Demonstrates using `Cell` objects for granular control over individual character grid units.
+
+Sometimes you need to render specific characters with unique styles outside of standard widgets. The `Cell` primitive allows you to build custom widgets or inject styled content into Tables.
+
+## Features Demonstrated
+
+- **Custom Widgets**: A `CheckeredBackground` widget built by rendering `Cell`s in a loop.
+- **Table Integration**: Mixing simple Strings and rich `Cell` objects in a Table row.
+- **Overlays**: Using `RatatuiRuby::Overlay` to stack widgets on top of each other.
+- **Modifiers**: Using `rapid_blink`, `bold`, and `dim` on individual cells.
+
+## Hotkeys
+
+- **q** / **Ctrl+c**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_cell_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create a custom widget (like a game board or specialized graph).
+- Style specific cells in a Table (e.g., Green "OK", Red "FAIL").
+- Understand how to position content precisely with `Cell`.