ratatui_ruby 0.4.0 → 0.6.0

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
+
+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).
+
+![Demo](/doc/images/widget_box_demo.png)

data/examples/{box_demo → widget_box_demo}/app.rb

@@ -6,7 +6,22 @@
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
-class BoxDemoApp
+# Demonstrates visual container attributes with interactive cycling.
+#
+# Widgets often float in void. Without boundaries, interfaces become a chaotic mess of text. Users need structure to parse information.
+#
+# This demo showcases the <tt>Block</tt> widget. It provides an interactive playground where you can cycle through different border types, colors, and title alignments in real-time.
+#
+# Use it to understand how to define distinct areas and create visual hierarchy in your terminal interface.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_box_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_box_demo.png
+class WidgetBoxDemo
   def initialize
     # Border Types (ratatui native styles)
     @border_types = [
@@ -15,7 +30,7 @@ class BoxDemoApp
       { name: "Double", type: :double },
       { name: "Thick", type: :thick },
       { name: "Quadrant Inside", type: :quadrant_inside },
-      { name: "Quadrant Outside", type: :quadrant_outside }
+      { name: "Quadrant Outside", type: :quadrant_outside },
     ]
     @border_type_index = 0
 
@@ -23,14 +38,32 @@ class BoxDemoApp
     # NOTE: We define these ONCE in initialize for efficiency.
     @border_sets = [
       { name: "None", set: nil },
-      { name: "Digits (Short)", set: {
-        tl: "1", tr: "2", bl: "3", br: "4",
-        vl: "5", vr: "6", ht: "7", hb: "8"
-      }},
-      { name: "Letters (Long)", set: {
-        top_left: "A", top_right: "B", bottom_left: "C", bottom_right: "D",
-        vertical_left: "E", vertical_right: "F", horizontal_top: "G", horizontal_bottom: "H"
-      }}
+      {
+name: "Digits (Short)",
+set: {
+        tl: "1",
+        tr: "2",
+        bl: "3",
+        br: "4",
+        vl: "5",
+        vr: "6",
+        ht: "7",
+        hb: "8",
+      },
+},
+      {
+name: "Letters (Long)",
+set: {
+        top_left: "A",
+        top_right: "B",
+        bottom_left: "C",
+        bottom_right: "D",
+        vertical_left: "E",
+        vertical_right: "F",
+        horizontal_top: "G",
+        horizontal_bottom: "H",
+      },
+},
     ]
     @border_set_index = 0
 
@@ -39,26 +72,26 @@ class BoxDemoApp
       { name: "Red", color: "red" },
       { name: "Blue", color: "blue" },
       { name: "Yellow", color: "yellow" },
-      { name: "Magenta", color: "magenta" }
+      { name: "Magenta", color: "magenta" },
     ]
     @color_index = 0
 
     @title_alignments = [
       { name: "Left", alignment: :left },
       { name: "Center", alignment: :center },
-      { name: "Right", alignment: :right }
+      { name: "Right", alignment: :right },
     ]
     @title_alignment_index = 0
 
     @styles = [
       { name: "Default", style: nil },
-      { name: "Blue on White", style: { fg: "blue", bg: "white", modifiers: [:bold] } }
+      { name: "Blue on White", style: { fg: "blue", bg: "white", modifiers: [:bold] } },
     ]
     @style_index = 0
 
     @title_styles = [
       { name: "Default", style: nil },
-      { name: "Yellow Bold Underlined", style: { fg: "yellow", modifiers: [:bold, :underlined] } }
+      { name: "Yellow Bold Underlined", style: { fg: "yellow", modifiers: [:bold, :underlined] } },
     ]
     @title_style_index = 0
 
@@ -66,15 +99,18 @@ class BoxDemoApp
       { name: "Default (no border style)", style: nil },
       { name: "Bold Red", style: { fg: "red", modifiers: [:bold] } },
       { name: "Cyan Italic", style: { fg: "cyan", modifiers: [:italic] } },
-      { name: "Magenta Dim", style: { fg: "magenta", modifiers: [:dim] } }
+      { name: "Magenta Dim", style: { fg: "magenta", modifiers: [:dim] } },
     ]
     @border_style_index = 0
 
-    @hotkey_style = RatatuiRuby::Style.new(modifiers: [:bold, :underlined])
+    @hotkey_style = nil # Initialized in run when tui is available
   end
 
   def run
-    RatatuiRuby.run do
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @hotkey_style = tui.style(modifiers: [:bold, :underlined])
+
       loop do
         render
         break if handle_input == :quit
@@ -82,13 +118,11 @@ class BoxDemoApp
     end
   end
 
-  private
-
-  def render
+  private def render
     # Get current values
     border_type_config = @border_types[@border_type_index]
     border_set_config = @border_sets[@border_set_index]
-    
+
     color_config = @colors[@color_index]
     title_alignment_config = @title_alignments[@title_alignment_index]
     style_config = @styles[@style_index]
@@ -106,7 +140,7 @@ class BoxDemoApp
       type_display += " (Overridden)"
     end
 
-    block = RatatuiRuby::Block.new(
+    block = @tui.block(
       title: "Box Demo",
       title_alignment: title_alignment_config[:alignment],
       title_style: title_style_config[:style],
@@ -119,72 +153,73 @@ class BoxDemoApp
     )
 
     # Main content
-    main_panel = RatatuiRuby::Paragraph.new(
+    main_panel = @tui.paragraph(
       text: "Arrow Keys: Change Color\n\nCurrent Color: #{color_config[:name]}",
-      block: block,
+      block:,
       fg: style_config[:style] ? nil : color_config[:color],
       style: style_config[:style],
       alignment: :center
     )
 
     # Bottom control panel
-    control_panel = RatatuiRuby::Block.new(
+    control_panel = @tui.block(
       title: "Controls",
       borders: [:all],
       children: [
-        RatatuiRuby::Paragraph.new(
+        @tui.paragraph(
           text: [
             # Line 1: Main Controls
-            RatatuiRuby::Text::Line.new(spans: [
-              RatatuiRuby::Text::Span.new(content: "↑↓←→", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Color (#{color_config[:name]})  "),
-              RatatuiRuby::Text::Span.new(content: "q", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Quit")
+            @tui.text_line(spans: [
+              @tui.text_span(content: "↑↓←→", style: @hotkey_style),
+              @tui.text_span(content: ": Color (#{color_config[:name]})  "),
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
             ]),
             # Line 2: Borders
-            RatatuiRuby::Text::Line.new(spans: [
-              RatatuiRuby::Text::Span.new(content: "space", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Border Type (#{type_display})  "),
-              RatatuiRuby::Text::Span.new(content: "c", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Border Set (#{border_set_config[:name]})")
+            @tui.text_line(spans: [
+              @tui.text_span(content: "space", style: @hotkey_style),
+              @tui.text_span(content: ": Border Type (#{type_display})  "),
+              @tui.text_span(content: "c", style: @hotkey_style),
+              @tui.text_span(content: ": Border Set (#{border_set_config[:name]})"),
             ]),
             # Line 3: Styles
-            RatatuiRuby::Text::Line.new(spans: [
-              RatatuiRuby::Text::Span.new(content: "s", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Style (#{style_config[:name]})  "),
-              RatatuiRuby::Text::Span.new(content: "b", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Border Style (#{border_style_config[:name]})")
+            @tui.text_line(spans: [
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Style (#{style_config[:name]})  "),
+              @tui.text_span(content: "b", style: @hotkey_style),
+              @tui.text_span(content: ": Border Style (#{border_style_config[:name]})"),
             ]),
             # Line 4: Title
-            RatatuiRuby::Text::Line.new(spans: [
-              RatatuiRuby::Text::Span.new(content: "enter", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Align Title (#{title_alignment_config[:name]})  "),
-              RatatuiRuby::Text::Span.new(content: "t", style: @hotkey_style),
-              RatatuiRuby::Text::Span.new(content: ": Title Style (#{title_style_config[:name]})")
-            ])
+            @tui.text_line(spans: [
+              @tui.text_span(content: "enter", style: @hotkey_style),
+              @tui.text_span(content: ": Align Title (#{title_alignment_config[:name]})  "),
+              @tui.text_span(content: "t", style: @hotkey_style),
+              @tui.text_span(content: ": Title Style (#{title_style_config[:name]})"),
+            ]),
           ]
-        )
+        ),
       ]
     )
 
-    # Vertical Layout
-    layout = RatatuiRuby::Layout.new(
-      direction: :vertical,
-      constraints: [
-        RatatuiRuby::Constraint.fill(1),
-        RatatuiRuby::Constraint.length(6),
-      ],
-      children: [main_panel, control_panel]
-    )
-
-    # 2. Render
-    RatatuiRuby.draw(layout)
+    # 2. Render with Frame API
+    @tui.draw do |frame|
+      main_rect, control_rect = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+      frame.render_widget(main_panel, main_rect)
+      frame.render_widget(control_panel, control_rect)
+    end
   end
 
-  def handle_input
+  private def handle_input
     # 3. Events
-    case RatatuiRuby.poll_event
-    in {type: :key, code: "q"} | {type: :key, code: "c", modifiers: ["ctrl"]}
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
       :quit
     in type: :key, code: "up"
       @color_index = (@color_index - 1) % @colors.size
@@ -212,5 +247,4 @@ class BoxDemoApp
   end
 end
 
-BoxDemoApp.new.run if __FILE__ == $0
-
+WidgetBoxDemo.new.run if __FILE__ == $0

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
+
+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.
+
+![Demo](/doc/images/widget_calendar_demo.png)

data/examples/widget_calendar_demo/app.rb

@@ -0,0 +1,109 @@
+# 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 monthly calendar attributes with interactive cycling.
+#
+# Dates are complex. Rendering them in a grid requires calculation of leap years, month lengths, and day-of-week offsets.
+# Use this widget to skip the boilerplate.
+#
+# This demo showcases the <tt>Calendar</tt> widget. It provides an interactive playground where you can toggle headers, weekday labels, and event highlights in real-time.
+#
+# Use it to understand how to render time-based data grids efficiently.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_calendar_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_calendar_demo.png
+class WidgetCalendarDemo
+  def run
+    RatatuiRuby.run do |tui|
+      show_header = true
+      show_weekdays = true
+      show_surrounding = false
+      show_events = true
+      hotkey_style = tui.style(modifiers: [:bold])
+
+      loop do
+        now = Time.now
+        surrounding_style = show_surrounding ? tui.style(fg: "gray", modifiers: [:dim]) : nil
+
+        events_map = if show_events
+          {
+            now => tui.style(fg: "green", modifiers: [:bold]),
+            (now + (86400 * 2)) => tui.style(fg: "red", modifiers: [:underlined]),
+            (now - (86400 * 5)) => tui.style(fg: "blue", bg: "white"),
+          }
+        else
+          {}
+        end
+
+        calendar = tui.calendar(
+          year: now.year,
+          month: now.month,
+          events: events_map,
+          header_style: tui.style(fg: "yellow", modifiers: [:bold]),
+          show_month_header: show_header,
+          show_weekdays_header: show_weekdays,
+          show_surrounding: surrounding_style,
+          block: tui.block(borders: [:top, :left, :right])
+        )
+
+        controls = tui.paragraph(
+          text: [
+            tui.text_line(spans: [
+              tui.text_span(content: " h/w/s/e", style: hotkey_style),
+              tui.text_span(content: ": Toggle Header/Weekdays/Surrounding/Events  "),
+              tui.text_span(content: "q", style: hotkey_style),
+              tui.text_span(content: ": Quit"),
+            ]),
+            tui.text_line(spans: [
+              tui.text_span(content: " Events: ", style: hotkey_style),
+              tui.text_span(content: "Today (Green), +2d (Red), -5d (Blue) (#{show_events ? 'On' : 'Off'})"),
+            ]),
+          ],
+          block: tui.block(title: " Controls ", borders: [:all])
+        )
+
+        tui.draw do |frame|
+          calendar_area, controls_area = tui.layout_split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              tui.constraint_min(0),
+              tui.constraint_length(4),
+            ]
+          )
+          frame.render_widget(calendar, calendar_area)
+          frame.render_widget(controls, controls_area)
+        end
+
+        case tui.poll_event
+        in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+          break
+        in type: :key, code: "h"
+          show_header = !show_header
+        in type: :key, code: "w"
+          show_weekdays = !show_weekdays
+        in type: :key, code: "s"
+          show_surrounding = !show_surrounding
+        in type: :key, code: "e"
+          show_events = !show_events
+        else
+          nil
+        end
+
+        sleep 0.05
+      end
+    end
+  end
+end
+
+WidgetCalendarDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_canvas_demo/README.md

@@ -0,0 +1,27 @@
+# Canvas Widget Demo
+<!--
+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
+
+![Screenshot of Canvas Widget Demo](../../doc/images/widget_canvas_demo.png)
+
+## 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
+
+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`.
+
+![Demo](/doc/images/widget_cell_demo.png)