ratatui_ruby 1.3.0 → 1.4.0

data/examples/app_external_editor/app.rb

@@ -1,344 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-require "tempfile"
-
-# Disable experimental warnings for line_count
-RatatuiRuby.experimental_warnings = false
-
-# External Editor Example
-#
-# Demonstrates full lifecycle control for temporarily exiting the TUI
-# to invoke an external editor, then re-entering—like editing a commit
-# message in lazygit.
-#
-# This example uses the low-level API (init_terminal/restore_terminal)
-# instead of RatatuiRuby.run, which is required when you need to
-# repeatedly enter and exit raw mode during a session.
-#
-# Features:
-# - `e` edits this example's README.md
-# - `s` edits a scratch file; saved content appears in a split pane
-# - Focus-aware scrolling with visual indicators
-# - Mouse scroll on hover
-class AppExternalEditor
-  README_PATH = File.expand_path("README.md", __dir__)
-
-  def initialize
-    @tui = RatatuiRuby::TUI.new
-    @readme_scroll = 0
-    @scratch_scroll = 0
-    @readme_content = File.read(README_PATH)
-    @scratch = Tempfile.new(["scratch", ".md"])
-    @scratch_content = nil
-    @focus = :readme
-
-    # Cached geometry (set during calculate_layout)
-    @readme_area = nil
-    @scratch_area = nil
-    @readme_page_height = 10
-    @scratch_page_height = 10
-    @readme_line_count = 0
-    @scratch_line_count = 0
-  end
-
-  def run
-    loop do
-      action = tui_session
-      case action
-      when :quit then break
-      when :edit_readme then edit_file(README_PATH) { reload_readme }
-      when :edit_scratch then edit_file(@scratch.path) { reload_scratch }
-      end
-    end
-  ensure
-    @scratch.unlink
-  end
-
-  private def tui_session
-    RatatuiRuby.init_terminal
-    begin
-      loop do
-        @tui.draw do |frame|
-          calculate_layout(frame.area)   # Phase 1: Geometry (once per frame)
-          render(frame)                  # Phase 2: Draw
-        end
-        action = handle_input            # Phase 3: Input (uses cached geometry)
-        return action if action          # Early return triggers ensure block
-      end
-    ensure
-      RatatuiRuby.restore_terminal       # Always runs, even on early return
-    end
-  end
-
-  # Open an external editor on the given file.
-  #
-  # Note: The terminal is already restored when this method is called!
-  # The tui_session method's ensure block handles restore_terminal before
-  # we get here. After the editor closes, the run loop calls tui_session
-  # again which does init_terminal. This pattern avoids explicit
-  # save/restore calls at every handoff point.
-  private def edit_file(path)
-    editor = ENV.fetch("EDITOR", "vi")
-    system(editor, path)
-    yield if block_given?
-  end
-
-  # Phase 1: Calculate layout and cache all geometry
-  private def calculate_layout(area)
-    content_area, @controls_area = @tui.layout_split(
-      area,
-      direction: :vertical,
-      constraints: [
-        @tui.constraint_fill(1),
-        @tui.constraint_length(3),
-      ]
-    )
-
-    if split_view?
-      @readme_area, @scratch_area = @tui.layout_split(
-        content_area,
-        direction: :horizontal,
-        constraints: [
-          @tui.constraint_percentage(50),
-          @tui.constraint_percentage(50),
-        ]
-      )
-    else
-      @readme_area = content_area
-      @scratch_area = nil
-    end
-
-    # Calculate wrapped line counts and page heights
-    calculate_readme_geometry
-    calculate_scratch_geometry if split_view?
-
-    # Clamp scroll positions now that we have accurate geometry
-    clamp_scroll_positions
-  end
-
-  private def calculate_readme_geometry
-    block = @tui.block(borders: [:all])
-    inner = block.inner(@readme_area)
-    @readme_page_height = inner.height
-
-    paragraph = @tui.paragraph(text: @readme_content, wrap: true, block:)
-    @readme_line_count = paragraph.line_count(inner.width)
-  end
-
-  private def calculate_scratch_geometry
-    return unless @scratch_area
-
-    block = @tui.block(borders: [:all])
-    inner = block.inner(@scratch_area)
-    @scratch_page_height = inner.height
-
-    paragraph = @tui.paragraph(text: @scratch_content || "", wrap: true, block:)
-    @scratch_line_count = paragraph.line_count(inner.width)
-  end
-
-  private def clamp_scroll_positions
-    @readme_scroll = @readme_scroll.clamp(0, max_readme_scroll)
-    @scratch_scroll = @scratch_scroll.clamp(0, max_scratch_scroll) if split_view?
-  end
-
-  # Phase 2: Render using cached geometry
-  private def render(frame)
-    render_readme(frame)
-    render_scratch(frame) if split_view?
-    render_controls(frame)
-  end
-
-  private def split_view? = @scratch_content && !@scratch_content.strip.empty?
-
-  private def render_readme(frame)
-    focused = @focus == :readme
-    paragraph = @tui.paragraph(
-      text: @readme_content,
-      scroll: [@readme_scroll, 0],
-      wrap: true,
-      block: @tui.block(
-        title: "README.md (#{@readme_scroll + 1}-#{[@readme_scroll + @readme_page_height, @readme_line_count].min}/#{@readme_line_count})",
-        borders: [:all],
-        border_style: focused ? { fg: "cyan" } : { fg: "dark_gray" }
-      )
-    )
-    frame.render_widget(paragraph, @readme_area)
-
-    # Stateful scrollbar with viewport_content_length
-    # content_length = max_scroll + 1, so position=max_scroll => content_length-1 => thumb at bottom
-    scrollbar = @tui.scrollbar(content_length: 0, position: 0, orientation: :vertical, track_symbol: nil)
-    state = RatatuiRuby::ScrollbarState.new(max_readme_scroll + 1)
-    state.position = @readme_scroll
-    state.viewport_content_length = @readme_page_height
-    frame.render_stateful_widget(scrollbar, @readme_area, state)
-  end
-
-  private def render_scratch(frame)
-    focused = @focus == :scratch
-    paragraph = @tui.paragraph(
-      text: @scratch_content,
-      scroll: [@scratch_scroll, 0],
-      wrap: true,
-      block: @tui.block(
-        title: "Scratch (#{@scratch_scroll + 1}-#{[@scratch_scroll + @scratch_page_height, @scratch_line_count].min}/#{@scratch_line_count})",
-        borders: [:all],
-        border_style: focused ? { fg: "yellow" } : { fg: "dark_gray" }
-      )
-    )
-    frame.render_widget(paragraph, @scratch_area)
-
-    # Stateful scrollbar with viewport_content_length
-    scrollbar = @tui.scrollbar(content_length: 0, position: 0, orientation: :vertical, track_symbol: nil)
-    state = RatatuiRuby::ScrollbarState.new(max_scratch_scroll + 1)
-    state.position = @scratch_scroll
-    state.viewport_content_length = @scratch_page_height
-    frame.render_stateful_widget(scrollbar, @scratch_area, state)
-  end
-
-  private def render_controls(frame)
-    spans = [
-      @tui.text_span(content: "↑/↓", style: hotkey_style),
-      @tui.text_span(content: ": Scroll  "),
-      @tui.text_span(content: "e", style: hotkey_style),
-      @tui.text_span(content: ": Edit README  "),
-      @tui.text_span(content: "s", style: hotkey_style),
-      @tui.text_span(content: ": Edit Scratch  "),
-    ]
-    if split_view?
-      spans += [
-        @tui.text_span(content: "Tab", style: hotkey_style),
-        @tui.text_span(content: ": Focus  "),
-      ]
-    end
-    spans += [
-      @tui.text_span(content: "q", style: hotkey_style),
-      @tui.text_span(content: ": Quit"),
-    ]
-
-    paragraph = @tui.paragraph(
-      text: [@tui.text_line(spans:)],
-      alignment: :center,
-      block: @tui.block(title: "Controls", borders: [:all])
-    )
-    frame.render_widget(paragraph, @controls_area)
-  end
-
-  private def hotkey_style = @tui.style(modifiers: [:bold, :underlined])
-
-  # Phase 3: Handle input using cached geometry
-  private def handle_input
-    case @tui.poll_event
-    # Quit
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-
-    # Edit actions
-    in { type: :key, code: "e" }
-      :edit_readme
-    in { type: :key, code: "s" }
-      :edit_scratch
-
-    # Focus switching (only in split view)
-    in { type: :key, code: "tab" } | { type: :key, code: "backtab" } |
-       { type: :key, code: "left" } | { type: :key, code: "right" } |
-       { type: :key, code: "h" } | { type: :key, code: "l" } if split_view?
-      switch_focus
-      nil
-
-    # Keyboard scrolling
-    in { type: :key, code: "up" } | { type: :key, code: "k" }
-      scroll_up
-      nil
-    in { type: :key, code: "down" } | { type: :key, code: "j" }
-      scroll_down
-      nil
-    in { type: :key, code: "page_up" }
-      scroll_up(page_height)
-      nil
-    in { type: :key, code: "page_down" }
-      scroll_down(page_height)
-      nil
-    in { type: :key, code: "home" }
-      scroll_to(0)
-      nil
-    in { type: :key, code: "end" }
-      scroll_to(max_scroll)
-      nil
-
-    # Mouse scroll - hit test to determine target pane
-    in { type: :mouse, kind: "scroll_up", x:, y: }
-      pane = pane_at(x, y)
-      scroll_pane_up(pane) if pane
-      nil
-    in { type: :mouse, kind: "scroll_down", x:, y: }
-      pane = pane_at(x, y)
-      scroll_pane_down(pane) if pane
-      nil
-
-    # Mouse click to focus (only in split view)
-    in { type: :mouse, kind: "down", x:, y: } if split_view?
-      pane = pane_at(x, y)
-      @focus = pane if pane
-      nil
-
-    else
-      nil
-    end
-  end
-
-  private def pane_at(x, y)
-    if @scratch_area&.contains?(x, y)
-      :scratch
-    elsif @readme_area&.contains?(x, y)
-      :readme
-    end
-  end
-
-  private def switch_focus
-    @focus = (@focus == :readme) ? :scratch : :readme
-  end
-
-  private def scroll_up(n = 1) = scroll_pane_up(@focus, n)
-  private def scroll_down(n = 1) = scroll_pane_down(@focus, n)
-
-  private def scroll_pane_up(pane, n = 1)
-    if pane == :readme
-      @readme_scroll = [@readme_scroll - n, 0].max
-    else
-      @scratch_scroll = [@scratch_scroll - n, 0].max
-    end
-  end
-
-  private def scroll_pane_down(pane, n = 1)
-    if pane == :readme
-      @readme_scroll = [@readme_scroll + n, max_readme_scroll].min
-    else
-      @scratch_scroll = [@scratch_scroll + n, max_scratch_scroll].min
-    end
-  end
-
-  private def scroll_to(y)
-    if @focus == :readme
-      @readme_scroll = y.clamp(0, max_readme_scroll)
-    else
-      @scratch_scroll = y.clamp(0, max_scratch_scroll)
-    end
-  end
-
-  private def max_scroll = (@focus == :readme) ? max_readme_scroll : max_scratch_scroll
-  private def max_readme_scroll = [@readme_line_count - @readme_page_height, 0].max
-  private def max_scratch_scroll = [@scratch_line_count - @scratch_page_height, 0].max
-  private def page_height = (@focus == :readme) ? @readme_page_height : @scratch_page_height
-
-  private def reload_readme = @readme_content = File.read(README_PATH)
-  private def reload_scratch = @scratch_content = File.read(@scratch.path)
-end
-
-AppExternalEditor.new.run if __FILE__ == $PROGRAM_NAME

data/examples/app_login_form/README.md

@@ -1,58 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Login Form Example
-
-[![Login Form](../../doc/images/app_login_form.png)](app.rb)
-
-Demonstrates how to create a modal overlay for user input.
-
-Many applications need to block interaction with the main UI while collecting specific information, like a login prompt or confirmation dialog. Managing the z-index and input focus for these overlays can be tricky.
-
-This example solves this by using the `Overlay` widget to stack a centered popup on top of a base layer, conditionally rendering the popup based on state.
-
-## Features Demonstrated
-
-- **Overlays:** Stacking widgets on top of each other using `tui.overlay`.
-- **Centering:** Positioning a widget in the center of the screen using `tui.center`.
-- **State Management:** Switching between "Base" and "Popup" views.
-- **Input Handling:** Capturing text input and handling specific keys (Enter, Esc) to trigger state changes.
-- **Cursor Positioning:** Manually calculating cursor position within a `Paragraph`.
-
-## Hotkeys
-
-### Form Mode
-- **Text Input**: Type to enter username (supports all characters including 'q').
-- **Backspace**: Deletes the last character.
-- **Enter**: Submits the form and opens the success popup.
-- **Esc**: Quits the application.
-- **Ctrl+C**: Quits the application.
-
-### Popup Mode
-- **q**: Closes the popup and quits the application.
-- **Ctrl+C**: Quits the application.
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/app_login_form/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Create a modal dialog or popup.
-- Center a widget on the screen (vertically and horizontally).
-- Implement a simple text input field with cursor management.
-- layer widgets using the `Overlay` widget.
-
-[Read the source code →](app.rb)

data/examples/app_login_form/app.rb

@@ -1,109 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-
-class AppLoginForm
-  PREFIX = "Enter Username: [ "
-  SUFFIX = " ]"
-
-  def initialize
-    @username = ""
-    @show_popup = false
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      @tui = tui
-      loop do
-        render
-        break if handle_input == :quit
-      end
-    end
-  end
-
-  private def render
-    # 1. Base Layer Construction
-    # We want a cursor relative to the paragraph.
-    # So we wrap Paragraph and Cursor in an Overlay, and put that Overlay in a Center.
-
-    # Calculate cursor position
-    # Border takes 1 cell.
-    # Cursor X = 1 (border) + PREFIX.length + username.length
-    # Cursor Y = 1 (border + line 0)
-    cursor_x = 1 + PREFIX.length + @username.length
-    cursor_y = 1
-
-    # The content of the base form
-    form_content = @tui.overlay(layers: [
-      @tui.paragraph(
-        text: "#{PREFIX}#{@username}#{SUFFIX}",
-        block: @tui.block(borders: :all, title: "Login Form"),
-        alignment: :left
-      ),
-      @tui.cursor(x: cursor_x, y: cursor_y),
-    ])
-
-    # Center the form on screen
-    base_layer = @tui.center(
-      child: form_content,
-      width_percent: 50,
-      height_percent: 20
-    )
-
-    # 2. Popup Layer Construction
-    final_view = if @show_popup
-      popup_message = @tui.center(
-        child: @tui.paragraph(
-          text: "Login Successful!\nPress 'q' to quit.",
-          style: @tui.style(fg: :green, bg: :black),
-          block: @tui.block(borders: :all),
-          alignment: :center,
-          wrap: true
-        ),
-        width_percent: 30,
-        height_percent: 20
-      )
-
-      # Render Base Layer (background) THEN Popup Layer
-      @tui.overlay(layers: [base_layer, popup_message])
-    else
-      base_layer
-    end
-
-    # 3. Draw
-    @tui.draw do |frame|
-      frame.render_widget(final_view, frame.area)
-    end
-  end
-
-  private def handle_input
-    case @tui.poll_event
-    in { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-    in { type: :key, code: "q" } if @show_popup
-      :quit
-    in { type: :key, code: "enter" }
-      @show_popup ||= true
-      nil
-    in { type: :key, code: "backspace" }
-      @username.chop! unless @show_popup
-      nil
-    in { type: :key, code: "esc" }
-      :quit unless @show_popup
-    in { type: :key, code:, modifiers: [] }
-      # Simple text input (single character, no modifiers)
-      @username += code if !@show_popup && code.length == 1
-      nil
-    else
-      nil
-    end
-  end
-end
-
-AppLoginForm.new.run if __FILE__ == $0

data/examples/app_stateful_interaction/README.md

@@ -1,35 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Stateful Interaction Example
-
-[![Stateful Interaction](../../doc/images/app_stateful_interaction.png)](app.rb)
-
-This example demonstrates High-Fidelity Interaction using **Stateful Widget Rendering**.
-
-It showcases a "Database Viewer" layout where:
-1.  **Selection Persistence:** `ListState` and `TableState` objects persist across frames, maintaining selection without manual index tracking variables.
-2.  **Offset Read-back:** The application reads `state.offset` *after* rendering to know exactly which items were visible on screen.
-3.  **Mouse Interaction:** Using the read-back offset, we can calculate exactly which row was clicked, even when the specific item wasn't drawn at that absolute Y position due to scrolling.
-
-## Key Concept: The "Read-back" Loop
-
-Standard immediate-mode interaction often requires you to re-calculate layout logic to determine what was clicked.
-
-In `ratatui_ruby`'s Stateful Rendering:
-1.  **Update**: You modify `state` (e.g., `state.select(1)`).
-2.  **Render**: You pass `state` to `render_stateful_widget`. Ratatui's Rust backend calculates layout and **updates** `state.offset` in-place if scrolling happened.
-3.  **Interact**: On the next event loop, you use `state.offset` to correctly map mouse coordinates to data indices.
-
-## Hotkeys
-
-| Key | Action |
-| --- | --- |
-| `↑` / `↓` | Scroll the active pane |
-| `Tab` / `←` / `→` | Switch active pane (List vs Table) |
-| `Mouse Click` | Select the clicked row (Works with scrolling!) |
-| `q` | Quit |
-
-[Read the source code →](app.rb)