ratatui_ruby 1.3.0 → 1.4.0

data/examples/widget_ratatui_logo/app.rb

@@ -1,104 +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 branding visualization with the official logo.
-#
-# Branding is important for identity. Users need to recognize the tools they use.
-#
-# This demo showcases the <tt>RatatuiLogo</tt> widget. It renders the logo in a centered layout.
-#
-# Use it to understand how to incorporate the project's visual identity into your terminal application.
-#
-# === Example
-#
-# Run the demo from the terminal:
-#
-#   ruby examples/widget_ratatui_logo/app.rb
-#
-# rdoc-image:/doc/images/widget_ratatui_logo.png
-class WidgetRatatuiLogo
-  def run
-    RatatuiRuby.run do |tui|
-      loop do
-        render(tui)
-        break if handle_input(tui) == :quit
-      end
-    end
-  end
-
-  private def render(tui)
-    tui.draw do |frame|
-      # Layout
-      layout = tui.layout_split(
-        frame.area,
-        direction: :vertical,
-        constraints: [
-          tui.constraint_fill(1), # Fill remaining space
-          tui.constraint_length(3),
-        ]
-      )
-
-      # Main Area
-      main_area = layout[0]
-
-      # Center the logo using nested Layouts
-      # Logo is roughly 47x8
-      # Vertical Center
-      v_center_layout = tui.layout_split(
-        main_area,
-        direction: :vertical,
-        flex: :center,
-        constraints: [tui.constraint_length(10)] # Height + margin
-      )
-
-      # Horizontal Center
-      h_center_layout = tui.layout_split(
-        v_center_layout[0],
-        direction: :horizontal,
-        flex: :center,
-        constraints: [tui.constraint_length(50)] # Width + margin
-      )
-
-      # Main content: The Logo
-      logo = RatatuiRuby::Widgets::RatatuiLogo.new
-      frame.render_widget(logo, h_center_layout[0])
-
-      # Control Panel
-      control_area = layout[1]
-
-      control_text = tui.text_line(spans: [
-        tui.text_span(content: "q", style: tui.style(modifiers: [:bold, :underlined])),
-        tui.text_span(content: ": Quit"),
-      ])
-
-      control_panel = tui.paragraph(
-        text: [control_text],
-        block: tui.block(
-          title: "Controls",
-          borders: [:top],
-          style: tui.style(fg: :dark_gray)
-        )
-      )
-
-      frame.render_widget(control_panel, control_area)
-    end
-  end
-
-  private def handle_input(tui)
-    case tui.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-    else
-      nil
-    end
-  end
-end
-
-WidgetRatatuiLogo.new.run if __FILE__ == $0

data/examples/widget_ratatui_mascot/README.md

@@ -1,43 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Ratatui Mascot Example
-
-[![widget_ratatui_mascot](../../doc/images/widget_ratatui_mascot.png)](app.rb)
-
-Demonstrates the project mascot widget for adding personality.
-
-Interfaces can feel clinical. A friendly mascot adds charm and brand identity to your terminal application.
-
-## Features Demonstrated
-
-- **RatatuiMascot Widget**: Renders the ASCII art mascot.
-- **Block Integration**: Wrapping the mascot in a bordered block title.
-
-## Hotkeys
-
-- **b**: Toggle Block Border (`block`)
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_ratatui_mascot/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Add visual flair to your UI.
-- Create a friendly empty state or success screen.
-
-[Read the source code →](app.rb)

data/examples/widget_ratatui_mascot/app.rb

@@ -1,95 +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 personality and charm with the project mascot.
-#
-# Interfaces without personality feel clinical and dry. Users appreciate a friendly face in their terminal.
-#
-# This demo showcases the <tt>RatatuiMascot</tt> widget. It provides an interactive playground where you can toggle the surrounding block.
-#
-# Use it to understand how to add a playful touch to your terminal dashboards or about screens.
-#
-# === Example
-#
-# Run the demo from the terminal:
-#
-#   ruby examples/widget_ratatui_mascot/app.rb
-#
-# rdoc-image:/doc/images/widget_ratatui_mascot.png
-class WidgetRatatuiMascot
-  def initialize
-    @show_block = true
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      loop do
-        tui.draw do |frame|
-          # Layout: Top (Mascot), Bottom (Controls)
-          layout = tui.layout_split(
-            frame.area,
-            direction: :vertical,
-            constraints: [
-              tui.constraint_fill(1),
-              tui.constraint_length(4),
-            ]
-          )
-
-          mascot_area = layout[0]
-          controls_area = layout[1]
-
-          # Mascot Widget
-          block = if @show_block
-            tui.block(
-              title: "Ratatui Mascot",
-              borders: [:all],
-              border_type: :rounded,
-              border_style: { fg: :green }
-            )
-          end
-
-          mascot = tui.ratatui_mascot(block:)
-          frame.render_widget(mascot, mascot_area)
-
-          # Controls
-          controls_text = [
-            tui.text_span(content: "q", style: tui.style(modifiers: [:bold, :underlined])),
-            tui.text_span(content: " Quit"),
-            tui.text_span(content: "   "),
-            tui.text_span(content: "b", style: tui.style(modifiers: [:bold, :underlined])),
-            tui.text_span(content: " Toggle Block #{@show_block ? '(On)' : '(Off)'}"),
-          ]
-
-          controls_paragraph = tui.paragraph(
-            text: tui.text_line(spans: controls_text),
-            block: tui.block(borders: [:top], title: "Controls")
-          )
-          frame.render_widget(controls_paragraph, controls_area)
-        end
-        break if handle_input(tui) == :quit
-      end
-    end
-  end
-
-  private def handle_input(tui)
-    event = tui.poll_event
-
-    if event.key?
-      case event.char
-      when "q" then :quit
-      when "b" then @show_block = !@show_block
-      end
-    elsif event.ctrl_c?
-      :quit
-    end
-  end
-end
-
-WidgetRatatuiMascot.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_rect/README.md

@@ -1,53 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Rect (Area, Rectangle) Example
-
-[![widget_rect](../../doc/images/widget_rect.png)](app.rb)
-
-Demonstrates the Rect geometry primitive and hit-testing patterns.
-
-TUI layouts are composed of rectangles. Understanding how to manipulate `Rect` objects, reuse them from the layout phase, and use them for mouse interaction is critical for building interactive apps.
-
-## Features Demonstrated
-
-- **Rect Attributes**: Investigating x, y, width, and height.
-- **Edge Accessors**: Using `left`, `right`, `top`, `bottom` instead of manual math.
-- **Size Methods**: Checking `area` and `empty?` for guard clauses.
-- **Geometry Transformations**: Computing `inner`, `offset`, `union`, and `clamp`.
-- **Iterators**: Traversing `rows`, `columns`, and `positions`.
-- **Cached Layout Pattern**: Computing constraints in the render loop and reusing the resulting `Rect`s in the event loop for logic.
-- **Hit Testing**: Using `Rect#contains?(x, y)` to determine if a mouse click happened inside a specific panel.
-
-## Hotkeys
-
-- **Arrows (←/→)**: Expand/Shrink Sidebar Width (Layout Constraint)
-- **Arrows (↑/↓)**: Navigate Menu Selection (`selected_index`)
-- **Mouse Click**: Click anywhere to see which Rect detects the hit (`contains?`)
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_rect/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Handle mouse clicks on specific buttons or areas.
-- Create resizable panes (like a split pane in an IDE).
-- Debug layout issues by inspecting Rect coordinates.
-- Compute inner padding, bounding boxes, or clamped popups.
-- Iterate over rows, columns, or individual positions within a region.
-
-[Read the source code →](app.rb)

data/examples/widget_rect/app.rb

@@ -1,222 +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"
-
-# Rect Widget Showcase
-#
-# Demonstrates the Rect class and the Cached Layout Pattern.
-#
-# Rect is the fundamental geometry primitive for TUI layout. This example shows:
-# - Rect attributes: x, y, width, height
-# - Edge accessors: left, right, top, bottom
-# - Geometry methods: area, empty?, union, inner, offset, clamp
-# - Iterators: rows, columns, positions
-# - Rect#contains? for hit testing mouse clicks
-# - Layout.split returning cached rects for reuse
-#
-# Controls:
-#   ←/→: Adjust sidebar width
-#   ↑/↓: Navigate menu items
-#   Mouse: Click panels to test Rect#contains?
-#   q: Quit
-class WidgetRect
-  MENU_ITEMS = ["Dashboard", "Analytics", "Settings", "Logs", "Help"].freeze
-
-  def initialize
-    @sidebar_width = 20
-    @selected_index = 0
-    @last_action = "Click any panel to test Rect#contains?"
-    @click_count = 0
-    @sidebar_rect = nil
-    @main_rect = nil
-    @controls_rect = nil
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      @tui = tui
-      @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
-      @label_style = @tui.style(modifiers: [:bold])
-      @dim_style = @tui.style(fg: :dark_gray)
-
-      loop do
-        render
-        break if handle_input == :quit
-      end
-    end
-  end
-
-  private def render
-    @tui.draw do |frame|
-      @main_rect, @controls_rect = @tui.layout_split(
-        frame.area,
-        direction: :vertical,
-        constraints: [
-          @tui.constraint_fill(1),
-          @tui.constraint_length(5),
-        ]
-      )
-
-      @sidebar_rect, @content_rect = @tui.layout_split(
-        @main_rect,
-        direction: :horizontal,
-        constraints: [
-          @tui.constraint_length(@sidebar_width),
-          @tui.constraint_fill(1),
-        ]
-      )
-
-      render_sidebar(frame)
-      render_content(frame)
-      render_controls(frame)
-    end
-  end
-
-  private def render_sidebar(frame)
-    sidebar = @tui.list(
-      items: MENU_ITEMS,
-      selected_index: @selected_index,
-      highlight_style: @tui.style(fg: :black, bg: :white, modifiers: [:bold]),
-      highlight_symbol: "> ",
-      block: @tui.block(title: "Menu", borders: [:all])
-    )
-    frame.render_widget(sidebar, @sidebar_rect)
-  end
-
-  private def render_content(frame)
-    r = @content_rect
-    inner_r = r.inner(2)
-    offset_r = r.offset(3, 2)
-    bounds = RatatuiRuby::Layout::Rect.new(x: 0, y: 0, width: 50, height: 20)
-    clamped = r.clamp(bounds)
-    union_r = r.union(@sidebar_rect)
-
-    # Extract position and size from rect
-    pos = r.position # => Position(x:, y:)
-    size = r.size    # => Size(width:, height:)
-
-    text_content = [
-      @tui.text_line(spans: [
-        @tui.text_span(content: "Active View: ", style: @label_style),
-        @tui.text_span(content: MENU_ITEMS[@selected_index], style: @tui.style(fg: :green)),
-      ]),
-      @tui.text_line(spans: [
-        @tui.text_span(content: "Rect Attributes ", style: @label_style),
-        @tui.text_span(content: "(from Layout.split):", style: @dim_style),
-      ]),
-      "  x:#{r.x} y:#{r.y} width:#{r.width} height:#{r.height}",
-      @tui.text_line(spans: [
-        @tui.text_span(content: "Edge Accessors:", style: @label_style),
-      ]),
-      "  left:#{r.left} right:#{r.right} top:#{r.top} bottom:#{r.bottom}",
-      @tui.text_line(spans: [
-        @tui.text_span(content: "Conversion Methods ", style: @label_style),
-        @tui.text_span(content: "(as_position/as_size):", style: @dim_style),
-      ]),
-      "  Position: x=#{pos.x} y=#{pos.y}  Size: #{size.width}x#{size.height}",
-      @tui.text_line(spans: [
-        @tui.text_span(content: "Geometry Transformations:", style: @label_style),
-      ]),
-      "  inner(2): x:#{inner_r.x} y:#{inner_r.y} w:#{inner_r.width} h:#{inner_r.height}",
-      "  offset(3,2): x:#{offset_r.x} y:#{offset_r.y}  clamp: x:#{clamped.x} y:#{clamped.y}",
-      "  union(sidebar): w:#{union_r.width} h:#{union_r.height}",
-      @tui.text_line(spans: [
-        @tui.text_span(content: "Hit Testing ", style: @label_style),
-        @tui.text_span(content: "(Rect#contains?):", style: @dim_style),
-      ]),
-      "  Clicks: #{@click_count}  |  #{@last_action}",
-    ]
-
-    paragraph = @tui.paragraph(
-      text: text_content,
-      block: @tui.block(title: "Content", borders: [:all])
-    )
-    frame.render_widget(paragraph, @content_rect)
-  end
-
-  private def render_controls(frame)
-    controls = @tui.block(
-      title: "Controls",
-      borders: [:all],
-      children: [
-        @tui.paragraph(
-          text: [
-            @tui.text_line(spans: [
-              @tui.text_span(content: "←", style: @hotkey_style),
-              @tui.text_span(content: "/"),
-              @tui.text_span(content: "→", style: @hotkey_style),
-              @tui.text_span(content: ": Sidebar width  "),
-              @tui.text_span(content: "↑", style: @hotkey_style),
-              @tui.text_span(content: "/"),
-              @tui.text_span(content: "↓", style: @hotkey_style),
-              @tui.text_span(content: ": Menu selection  "),
-              @tui.text_span(content: "Click", style: @hotkey_style),
-              @tui.text_span(content: ": Hit test  "),
-              @tui.text_span(content: "q", style: @hotkey_style),
-              @tui.text_span(content: ": Quit"),
-            ]),
-          ]
-        ),
-      ]
-    )
-    frame.render_widget(controls, @controls_rect)
-  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: "left"
-      @sidebar_width = [@sidebar_width - 2, 10].max
-      @last_action = "Layout changed: sidebar_width=#{@sidebar_width}"
-      nil
-    in type: :key, code: "right"
-      @sidebar_width = [@sidebar_width + 2, 40].min
-      @last_action = "Layout changed: sidebar_width=#{@sidebar_width}"
-      nil
-    in type: :key, code: "up"
-      @selected_index = (@selected_index - 1) % MENU_ITEMS.size
-      @last_action = "Selected: #{MENU_ITEMS[@selected_index]}"
-      nil
-    in type: :key, code: "down"
-      @selected_index = (@selected_index + 1) % MENU_ITEMS.size
-      @last_action = "Selected: #{MENU_ITEMS[@selected_index]}"
-      nil
-    in type: :mouse, kind: "down", x: click_x, y: click_y
-      handle_click(click_x, click_y)
-      nil
-    else
-      nil
-    end
-  end
-
-  private def handle_click(x, y)
-    @click_count += 1
-
-    if @sidebar_rect&.contains?(x, y)
-      relative_y = y - @sidebar_rect.y - 1
-      if relative_y >= 0 && relative_y < MENU_ITEMS.size
-        old_item = MENU_ITEMS[@selected_index]
-        @selected_index = relative_y
-        new_item = MENU_ITEMS[@selected_index]
-        @last_action = "sidebar.contains?(#{x},#{y})=true → #{old_item}→#{new_item}"
-      else
-        @last_action = "sidebar.contains?(#{x},#{y})=true (empty area)"
-      end
-    elsif @content_rect&.contains?(x, y)
-      @last_action = "content.contains?(#{x},#{y})=true"
-    elsif @controls_rect&.contains?(x, y)
-      @last_action = "controls.contains?(#{x},#{y})=true"
-    else
-      @last_action = "No rect contains (#{x},#{y})"
-    end
-  end
-end
-
-WidgetRect.new.run if __FILE__ == $0

data/examples/widget_render/README.md

@@ -1,46 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Render (Custom Widget) Example
-
-[![widget_render](../../doc/images/widget_render.png)](app.rb)
-
-Demonstrates how to build Custom Widgets using absolute coordinates.
-
-Sometimes standard widgets aren't enough. You need to draw custom shapes, games, or graphs. This example shows how to implement the `render(area)` contract to draw anything you want while respecting layout boundaries.
-
-## Features Demonstrated
-
-- **Custom Widget Contract**: Implementing a class with `render(area)`.
-- **Coordinate Offsets**: Creating drawing logic that works regardless of where the widget is placed on screen (using `area.x + offset`).
-- **Composability**: Wrapping custom widgets in standard `Block`s with borders.
-
-## Hotkeys
-
-- **n**: Next Widget (Diagonal -> Checkerboard -> Border)
-- **p**: Previous Widget
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_render/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Build a game (Snake, Tetris) inside the terminal.
-- Create a specialized visualization (Network topology graph).
-- Draw custom UI elements not provided by the library.
-
-[Read the source code →](app.rb)