ratatui_ruby 0.3.1 → 0.5.0

data/examples/widget_block_padding/app.rb

@@ -0,0 +1,67 @@
+# 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 showing Block padding capabilities
+class WidgetBlockPadding
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        # 1. Uniform Padding
+        block1 = RatatuiRuby::Block.new(
+          title: "Uniform Padding (2)",
+          borders: [:all],
+          padding: 2
+        )
+        para1 = RatatuiRuby::Paragraph.new(
+          text: "This text is padded by 2 on all sides.\nNotice the space between the border and this text.",
+          block: block1
+        )
+
+        # 2. Directional Padding
+        block2 = RatatuiRuby::Block.new(
+          title: "Directional Padding [Left: 4, Right: 0, Top: 2, Bottom: 0]",
+          borders: [:all],
+          padding: [4, 0, 2, 0]
+        )
+        para2 = RatatuiRuby::Paragraph.new(
+          text: "This text has different padding per side.\nLeft: 4, Top: 2.",
+          block: block2
+        )
+
+        # Instructions
+        para3 = RatatuiRuby::Paragraph.new(
+          text: "Press 'q' to quit."
+        )
+
+        tui.draw do |frame|
+          # Layout
+          areas = RatatuiRuby::Layout.split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              RatatuiRuby::Constraint.length(10), # Uniform Padding
+              RatatuiRuby::Constraint.length(10), # Directional Padding
+              RatatuiRuby::Constraint.min(0),
+            ]
+          )
+
+          frame.render_widget(para1, areas[0])
+          frame.render_widget(para2, areas[1])
+          frame.render_widget(para3, areas[2])
+        end
+
+        event = tui.poll_event
+        break if event == "q" || event == :ctrl_c
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  WidgetBlockPadding.new.run
+end

data/examples/widget_block_titles/app.rb

@@ -0,0 +1,69 @@
+# 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"
+
+# Initialize the terminal
+class WidgetBlockTitles
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        # Create a layout with multiple blocks demonstrating titles
+        blocks = [
+          tui.block(
+            titles: [
+              { content: "Top Left", alignment: :left, position: :top },
+              { content: "Top Right", alignment: :right, position: :top },
+            ],
+            borders: [:all],
+            border_color: "cyan"
+          ),
+          tui.block(
+            titles: [
+              { content: "Bottom Left", alignment: :left, position: :bottom },
+              { content: "Bottom Center", alignment: :center, position: :bottom },
+              { content: "Bottom Right", alignment: :right, position: :bottom },
+            ],
+            borders: [:all],
+            border_color: "magenta"
+          ),
+          tui.block(
+            titles: [
+              "Simple String Title (Top Left Default)",
+              { content: "Mixed Title", alignment: :center, position: :bottom },
+            ],
+            borders: [:all],
+            border_color: "green"
+          ),
+        ]
+
+        tui.draw do |frame|
+          layout = tui.layout_split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              tui.constraint(:length, 10),
+              tui.constraint(:length, 10),
+              tui.constraint(:length, 10),
+            ]
+          )
+
+          layout.each_with_index do |area, i|
+            frame.render_widget(blocks[i], area) if blocks[i]
+          end
+        end
+
+        event = tui.poll_event
+        break if event == "q" || event == :ctrl_c
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  WidgetBlockTitles.new.run
+end

data/examples/widget_box_demo/app.rb

@@ -0,0 +1,250 @@
+# 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 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 = [
+      { name: "Plain", type: :plain },
+      { name: "Rounded", type: :rounded },
+      { name: "Double", type: :double },
+      { name: "Thick", type: :thick },
+      { name: "Quadrant Inside", type: :quadrant_inside },
+      { name: "Quadrant Outside", type: :quadrant_outside },
+    ]
+    @border_type_index = 0
+
+    # Custom Border Sets
+    # 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",
+      },
+},
+    ]
+    @border_set_index = 0
+
+    @colors = [
+      { name: "Green", color: "green" },
+      { name: "Red", color: "red" },
+      { name: "Blue", color: "blue" },
+      { name: "Yellow", color: "yellow" },
+      { name: "Magenta", color: "magenta" },
+    ]
+    @color_index = 0
+
+    @title_alignments = [
+      { name: "Left", alignment: :left },
+      { name: "Center", alignment: :center },
+      { name: "Right", alignment: :right },
+    ]
+    @title_alignment_index = 0
+
+    @styles = [
+      { name: "Default", style: nil },
+      { 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] } },
+    ]
+    @title_style_index = 0
+
+    @border_styles = [
+      { 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] } },
+    ]
+    @border_style_index = 0
+
+    @hotkey_style = nil # Initialized in run when tui is available
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @hotkey_style = tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  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]
+    title_style_config = @title_styles[@title_style_index]
+    border_style_config = @border_styles[@border_style_index]
+
+    # 1. State/View
+    # Use border_style if provided, otherwise fall back to border_color
+    effective_border_style = border_style_config[:style]
+    effective_border_color = effective_border_style ? nil : (style_config[:style] ? nil : color_config[:color])
+
+    # Show overridden status if border_set is active
+    type_display = border_type_config[:name]
+    if border_set_config[:set]
+      type_display += " (Overridden)"
+    end
+
+    block = @tui.block(
+      title: "Box Demo",
+      title_alignment: title_alignment_config[:alignment],
+      title_style: title_style_config[:style],
+      borders: [:all],
+      border_color: effective_border_color,
+      border_style: effective_border_style,
+      border_type: border_type_config[:type],
+      border_set: border_set_config[:set],
+      style: style_config[:style]
+    )
+
+    # Main content
+    main_panel = @tui.paragraph(
+      text: "Arrow Keys: Change Color\n\nCurrent Color: #{color_config[:name]}",
+      block:,
+      fg: style_config[:style] ? nil : color_config[:color],
+      style: style_config[:style],
+      alignment: :center
+    )
+
+    # Bottom control panel
+    control_panel = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            # Line 1: Main Controls
+            @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
+            @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
+            @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
+            @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]})"),
+            ]),
+          ]
+        ),
+      ]
+    )
+
+    # 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
+
+  private def handle_input
+    # 3. Events
+    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
+    in type: :key, code: "down"
+      @color_index = (@color_index + 1) % @colors.size
+    in type: :key, code: "left"
+      @color_index = (@color_index - 1) % @colors.size
+    in type: :key, code: "right"
+      @color_index = (@color_index + 1) % @colors.size
+    in type: :key, code: " "
+      @border_type_index = (@border_type_index + 1) % @border_types.size
+    in type: :key, code: "c"
+      @border_set_index = (@border_set_index + 1) % @border_sets.size
+    in type: :key, code: "enter"
+      @title_alignment_index = (@title_alignment_index + 1) % @title_alignments.size
+    in type: :key, code: "s"
+      @style_index = (@style_index + 1) % @styles.size
+    in type: :key, code: "t"
+      @title_style_index = (@title_style_index + 1) % @title_styles.size
+    in type: :key, code: "b"
+      @border_style_index = (@border_style_index + 1) % @border_styles.size
+    else
+      nil
+    end
+  end
+end
+
+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