ratatui_ruby 0.4.0 → 0.5.0

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/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_cell_demo/app.rb

@@ -0,0 +1,104 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# A custom widget that fills its area with a checkered pattern using Cell objects.
+class CheckeredBackground
+  def render(area)
+    cell = RatatuiRuby::Cell.new(char: "░", fg: :dark_gray)
+    commands = []
+    area.height.times do |y|
+      area.width.times do |x|
+        # Checkerboard logic
+        if (x + y).even?
+          # Use a dim cell for the background pattern
+          commands << RatatuiRuby::Draw.cell(area.x + x, area.y + y, cell)
+        end
+      end
+    end
+    commands
+  end
+end
+
+class WidgetCellDemo
+  def main
+    RatatuiRuby.run do |tui|
+      # Define some reusable cells for our table
+      ok_cell = RatatuiRuby::Cell.new(char: "OK", fg: :green)
+      fail_cell = RatatuiRuby::Cell.new(char: "FAIL", fg: :red, modifiers: ["bold"])
+      pending_cell = RatatuiRuby::Cell.new(char: "...", fg: :yellow, modifiers: ["dim"])
+
+      # A mix of Strings and Cells in rows
+      rows = [
+        ["Database", ok_cell],
+        ["Cache", ok_cell],
+        ["Worker", fail_cell],
+        ["Analytics", pending_cell],
+        ["Web Server", RatatuiRuby::Cell.new(char: "RESTARTING", fg: :blue, modifiers: ["rapid_blink"])],
+      ]
+
+      table = RatatuiRuby::Table.new(
+        header: ["Service", RatatuiRuby::Cell.new(char: "Status", modifiers: ["underlined"])],
+        rows:,
+        widths: [
+          RatatuiRuby::Constraint.percentage(70),
+          RatatuiRuby::Constraint.percentage(30),
+        ],
+        block: RatatuiRuby::Block.new(title: "System Status", borders: :all),
+        column_spacing: 1
+      )
+
+      # Main loop
+      loop do
+        tui.draw do |frame|
+          # Create a layout that holds both widgets
+          # We use a vertical layout:
+          # Top: Custom CheckeredBackground with specific height
+          # Bottom: Table using remaining space
+          top_area, bottom_area = RatatuiRuby::Layout.split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              RatatuiRuby::Constraint.length(10), # Top section
+              RatatuiRuby::Constraint.min(0), # Bottom section
+            ]
+          )
+
+          # Top Child: An Overlay of Paragraph on top of CheckeredBackground
+          overlay = RatatuiRuby::Overlay.new(
+            layers: [
+              CheckeredBackground.new,
+              RatatuiRuby::Center.new(
+                width_percent: 50,
+                height_percent: 50,
+                child: RatatuiRuby::Paragraph.new(
+                  text: "Custom Widget Demo\n(CheckeredBackground)",
+                  alignment: :center,
+                  block: RatatuiRuby::Block.new(borders: :all, title: "Overlay")
+                )
+              ),
+            ]
+          )
+          frame.render_widget(overlay, top_area)
+
+          # Bottom Child: The Table
+          frame.render_widget(table, bottom_area)
+        end
+
+        event = RatatuiRuby.poll_event
+        if event.is_a?(RatatuiRuby::Event::Key) && (event.code == "q" || (event.code == "c" && event.modifiers.include?("ctrl")))
+          break
+        end
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  WidgetCellDemo.new.main
+end