ratatui_ruby 1.3.0 → 1.4.0

data/examples/widget_box/app.rb

@@ -1,255 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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/app.rb
-#
-# rdoc-image:/doc/images/widget_box.png
-class WidgetBox
-  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 explicitly set; otherwise, only apply color picker
-    # color when no content style is set (preserves original border_color behavior)
-    effective_border_style = if border_style_config[:style]
-      border_style_config[:style]
-    elsif style_config[:style].nil?
-      @tui.style(fg: color_config[:color])
-    end
-
-    # 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",
-      title_alignment: title_alignment_config[:alignment],
-      title_style: title_style_config[:style],
-      borders: [:all],
-      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
-
-WidgetBox.new.run if __FILE__ == $0

data/examples/widget_calendar/README.md

@@ -1,48 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Calendar Widget Example
-
-[![widget_calendar](../../doc/images/widget_calendar.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_calendar/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)

data/examples/widget_calendar/app.rb

@@ -1,115 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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/app.rb
-#
-# rdoc-image:/doc/images/widget_calendar.png
-class WidgetCalendar
-  def initialize(date: nil)
-    @date = date
-  end
-
-  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 = @date || 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
-
-WidgetCalendar.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_canvas/README.md

@@ -1,31 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Canvas (Circle, Line, Point, Rectangle) Example
-
-[![widget_canvas](../../doc/images/widget_canvas.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/app.rb

@@ -1,130 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-
-# Canvas Widget
-# Demonstrates how to draw geometric shapes (Points, Lines, Rects, Circles)
-# on a high-resolution canvas.
-class WidgetCanvas
-  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 using terse aliases (circle, rectangle, point, map, label)
-      # These are shorter forms of shape_circle, shape_rectangle, etc.
-      shapes = []
-
-      # 1. Static Grid (Lines) - using shape_line (no terse alias for line)
-      (-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") - using terse 'circle' alias
-      shapes << @tui.circle(
-        x: @x_offset,
-        y: @y_offset,
-        radius: 10.0,
-        color: :green
-      )
-
-      # 3. Static Rectangle (Target) - using shape_rectangle (no 'rectangle' alias
-      #    to avoid confusion with Layout::Rect)
-      shapes << @tui.shape_rectangle(
-        x: 30.0,
-        y: 30.0,
-        width: 20.0,
-        height: 20.0,
-        color: :red
-      )
-
-      # 4. Points (Starfield) - using terse 'point' alias
-      # Deterministic "random" points
-      10.times do |i|
-        shapes << @tui.point(
-          x: ((i * 37) % 200) - 100.0,
-          y: ((i * 19) % 200) - 100.0
-        )
-      end
-
-      # 5. Connecting line from origin to player position
-      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", borders: [:all])
-      )
-
-      # Main area for canvas
-      layout = @tui.layout_split(
-        frame.area,
-        direction: :vertical,
-        constraints: [
-          @tui.constraint_fill(1),
-          @tui.constraint_length(2),
-        ]
-      )
-
-      frame.render_widget(canvas, layout[0])
-
-      # Query: Canvas#get_point maps canvas coordinates to normalized [0.0, 1.0] grid
-      normalized = canvas.get_point(@x_offset, @y_offset)
-      norm_str = normalized ? format("[%.2f, %.2f]", normalized[0], normalized[1]) : "nil"
-
-      # Controls showing query method demonstration (single concise line)
-      controls = @tui.paragraph(
-        text: [
-          @tui.text_line(spans: [
-            @tui.text_span(content: "q", style: @tui.style(modifiers: [:bold, :underlined])),
-            @tui.text_span(content: ": Quit  "),
-            @tui.text_span(content: "get_point → ", style: @tui.style(fg: :dark_gray)),
-            @tui.text_span(content: norm_str, style: @tui.style(fg: :cyan)),
-          ]),
-        ],
-        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
-
-WidgetCanvas.new.run if __FILE__ == $0

data/examples/widget_cell/README.md

@@ -1,45 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Cell Widget Example
-
-[![widget_cell](../../doc/images/widget_cell.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_cell/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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`.
-
-[Read the source code →](app.rb)