tui_tui 0.2.0 → 0.4.0

data/lib/tui_tui/modal/help.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../modal"
+
+module TuiTui
+  class Modal
+    # Key-binding cheat sheet modal.
+    class Help < Modal
+      COLGAP = 2
+
+      def initialize(title, entries, theme: Theme::DEFAULT)
+        @title = DisplayText.new(title)
+        @entries = entries.map { |keys, desc| [DisplayText.new(keys), DisplayText.new(desc)] }
+        @theme = theme
+      end
+
+      def handle(_key) = :close
+
+      # Any click dismisses the sheet, like any key does.
+      def handle_mouse(event) = event.action == :press ? :close : nil
+
+      def draw(canvas, size)
+        key_w = @entries.map { |keys, _| keys.width }.max || 0
+        body_w = @entries.map { |keys, desc| keys.width + COLGAP + desc.width }.max || 0
+        inner = [@title.width, body_w].max
+
+        rect, col = panel(canvas, inner: inner, body_rows: @entries.size + 2)
+
+        canvas.text(rect.row + 1, col, @title.truncate(inner), theme.title)
+        draw_entries(canvas, rect.row + 3, col, key_w)
+        canvas
+      end
+
+      private
+
+      def draw_entries(canvas, row, col, key_w)
+        @entries.each_with_index do |(keys, desc), index|
+          canvas.text(row + index, col, keys, theme.accent)
+          canvas.text(row + index, col + key_w + COLGAP, desc, theme.muted)
+        end
+      end
+    end
+  end
+end

data/lib/tui_tui/modal/pager.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "../span"
+require_relative "../line"
+require_relative "../rect"
+require_relative "../modal"
+require_relative "../key_intent"
+
+module TuiTui
+  class Modal
+    # Scrollable read-only text modal.
+    class Pager < Modal
+      MARGIN = 2
+      WHEEL = 3
+
+      # Each line may be a plain String, a `Line`, or an array of `Span`s, so a
+      # log/diff/error view can color whole lines or runs within them. Spans
+      # without a style fall back to theme.muted.
+      def initialize(title, lines, start: 0, close_keys: [], theme: Theme::DEFAULT)
+        @title = title
+        @theme = theme
+        @lines = lines.map { |line| normalize_line(line) }
+        @top = start
+        @page = 1
+        @close_keys = close_keys
+      end
+
+      def handle(key)
+        return :close if @close_keys.include?(key)
+
+        case KeyIntent.for(key)
+        when :up
+          scroll(-1)
+        when :down
+          scroll(1)
+        when :top
+          scroll(-@lines.size)
+        when :bottom
+          scroll(@lines.size)
+        when :cancel
+          :close
+        else
+          paginate(key)
+        end
+      end
+
+      def handle_mouse(event)
+        scroll(event.button == :wheel_up ? -WHEEL : WHEEL) if event.action == :wheel
+      end
+
+      def draw(canvas, size)
+        width = [size.cols - (MARGIN * 2), 20].max
+        height = [size.rows - (MARGIN * 2), 5].max
+        rect = Rect.centered(size, cols: width, rows: height)
+        canvas.frame(rect, style: theme.frame)
+
+        inner = width - 4
+        body = [height - 4, 1].max
+        @page = body
+        clamp(body)
+
+        canvas.text(rect.row + 1, rect.col + 2, DisplayText.new(title_line(body)).truncate(inner), theme.title)
+        body.times do |offset|
+          line = @lines[@top + offset]
+          next if line.nil?
+
+          canvas.line(rect.row + 3 + offset, rect.col + 2, line.truncate(inner))
+        end
+
+        canvas
+      end
+
+      private
+
+      # -> Line. Accepts a String, a Line, or a Span array; spans left unstyled
+      # default to theme.muted so a bare line still reads as muted body text.
+      def normalize_line(line)
+        spans = Line.coerce(line).spans.map { |span| Span[span.text, span.style || theme.muted] }
+        Line.new(spans)
+      end
+
+      def paginate(key)
+        case key
+        when " ", :pgdn
+          scroll(@page)
+        when "b", :pgup
+          scroll(-@page)
+        end
+      end
+
+      def scroll(delta)
+        @top += delta
+        nil
+      end
+
+      def clamp(body)
+        @top = @top.clamp(0, [@lines.size - body, 0].max)
+      end
+
+      def title_line(body)
+        last = [@top + body, @lines.size].min
+        "#{@title}  (#{@top + 1}-#{last}/#{@lines.size})"
+      end
+    end
+  end
+end

data/lib/tui_tui/modal/prompt.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../text_input"
+require_relative "../modal"
+require_relative "../key_code"
+
+module TuiTui
+  class Modal
+    # Single-line text input modal with terminal-column-aware cursor placement.
+    class Prompt < Modal
+      MIN_INNER = 24
+
+      def initialize(label, value: "", theme: Theme::DEFAULT)
+        @label = DisplayText.new(label)
+        @input = TextInput.new(value: value)
+        @theme = theme
+      end
+
+      def value = @input.value
+
+      def handle(key)
+        case key
+        when "\r"
+          [:ok, value]
+        when :escape, KeyCode::CTRL_C
+          :cancel
+        else
+          @input.handle_editing(key)
+          nil
+        end
+      end
+
+      def handle_mouse(event)
+        return nil unless event.action == :press && @text_row == event.row
+
+        @input.cursor = @input.index_at(event.col - @text_col, from: @scroll)
+        nil
+      end
+
+      def draw(canvas, size)
+        # Grow the panel to fit the value, but never past the screen: beyond that
+        # the value scrolls horizontally inside its column budget (see #viewport).
+        max_inner = [size.cols - (PAD * 2) - 2, MIN_INNER].max
+        desired = @label.width + 1 + DisplayText.new(value).width
+        inner = desired.clamp(MIN_INNER, max_inner)
+        rect, col = panel(canvas, inner: inner, body_rows: 1)
+
+        canvas.text(rect.row + 1, col, @label, theme.title)
+        @text_row = rect.row + 1
+        @text_col = col + @label.width + 1
+        draw_value(canvas, [inner - @label.width - 1, 1].max)
+        canvas
+      end
+
+      private
+
+      def draw_value(canvas, budget)
+        viewport = @input.viewport(budget)
+        @scroll = viewport.start
+        canvas.text(@text_row, @text_col, viewport.text, theme.text)
+        cursor_col = @text_col + viewport.cursor_col
+        canvas.text(@text_row, cursor_col, viewport.cursor_grapheme || " ", theme.cursor)
+      end
+    end
+  end
+end

data/lib/tui_tui/modal/select.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "../widget/scroll_list"
+require_relative "../widget/list"
+require_relative "../line"
+require_relative "../span"
+require_relative "../rect"
+require_relative "../modal"
+require_relative "../key_intent"
+
+module TuiTui
+  class Modal
+    # Scrollable list picker modal.
+    class Select < Modal
+      MAX_ROWS = 12
+      MIN_INNER = 16
+      WHEEL = 3
+
+      def initialize(title, items, default: 0, theme: Theme::DEFAULT)
+        @title = DisplayText.new(title)
+        @items = items.map { |item| DisplayText.new(item) }
+        @list = Widget::ScrollList.new(@items.size)
+        @list.go_to(default)
+        @theme = theme
+      end
+
+      def cursor = @list.cursor
+
+      def handle(key)
+        case KeyIntent.for(key)
+        when :up
+          nudge(-1)
+        when :down
+          nudge(1)
+        when :top
+          nudge_to(0)
+        when :bottom
+          nudge_to(@list.last)
+        when :cancel
+          :cancel
+        else
+          @list.cursor if ["\r", " "].include?(key)
+        end
+      end
+
+      # Wheel moves the highlighted item; a click on an item picks it. Returns the
+      # chosen index on a click, otherwise nil (stay open).
+      def handle_mouse(event)
+        case event.action
+        when :wheel
+          nudge(event.button == :wheel_up ? -WHEEL : WHEEL)
+        when :press
+          click(event)
+        end
+      end
+
+      def draw(canvas, size)
+        rows = visible_rows(size)
+        inner = [MIN_INNER, @title.width, *@items.map(&:width)].max
+        rect, text_col = panel(canvas, inner: inner, body_rows: rows + 2)
+
+        canvas.text(rect.row + 1, text_col, @title.truncate(inner), theme.title)
+        draw_items(canvas, rect.row + 3, text_col, inner, rows)
+        canvas
+      end
+
+      private
+
+      def nudge(delta)
+        @list.move(delta)
+        nil
+      end
+
+      def nudge_to(index)
+        @list.go_to(index)
+        nil
+      end
+
+      def visible_rows(size)
+        room = [size.rows - 4, 1].max
+        [@items.size, MAX_ROWS, room].min
+      end
+
+      def draw_items(canvas, row, col, inner, rows)
+        @items_rect = Rect.new(row: row, col: col, rows: rows, cols: inner)
+        Widget::List.new(@list).draw(canvas, @items_rect) do |index, focused|
+          Line[Span[@items[index].to_s, focused ? theme.selection : theme.text]]
+        end
+      end
+
+      # The item under a click, picked, or nil if the click missed the list.
+      def click(event)
+        return nil unless @items_rect
+
+        index = Widget::List.new(@list).index_at(@items_rect, event)
+        return nil if index.nil?
+
+        @list.go_to(index)
+        @list.cursor
+      end
+    end
+  end
+end

data/lib/tui_tui/modal.rb

@@ -3,6 +3,10 @@
 require_relative "rect"
 require_relative "theme"
 
+# used by subclasses
+require_relative "display_text"
+require_relative "style"
+
 module TuiTui
   # Base protocol and shared centered-panel framing for overlay widgets.
   class Modal

data/lib/tui_tui/modal_host.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "event"
+require_relative "events"
 
 module TuiTui
   # Host-side helper for the app that *owns* the current modal widget.
@@ -11,7 +11,7 @@ module TuiTui
   # the caller's on_result callback when the modal resolves.
   #
   #   host = TuiTui::ModalHost.new
-  #   host.open(TuiTui::Confirm.new("Quit?")) { |r| :quit if r == :ok }
+  #   host.open(TuiTui::Modal::Confirm.new("Quit?")) { |r| :quit if r == :ok }
   #   # in update(event):
   #   if host.open?
   #     outcome = host.handle(event)   # nil while open; on_result value once resolved

data/lib/tui_tui/rect.rb

@@ -12,6 +12,12 @@ module TuiTui
       )
     end
 
+    # The Rect covering a whole screen: row/col 1 over anything with
+    # Size-compatible `rows` / `cols` (a Size or a RenderContext).
+    def self.of(size)
+      new(row: 1, col: 1, rows: size.rows, cols: size.cols)
+    end
+
     def split_h(top_rows)
       top = Rect.new(row: row, col: col, rows: top_rows, cols: cols)
       bottom = Rect.new(row: row + top_rows, col: col, rows: rows - top_rows, cols: cols)
@@ -33,6 +39,35 @@ module TuiTui
       [left, right.shift_right(gutter)]
     end
 
+    # Split into stacked Rects, top to bottom, one per constraint:
+    # an Integer is a fixed number of rows, a Float a fraction of the whole
+    # (`(rows * f).round`), and :rest shares whatever the fixed and fractional
+    # segments leave over (several :rest split it evenly, leading ones taking
+    # the indivisible remainder). Sizes resolve front to back, each clamped to
+    # what is still left, so an undersized rect squashes trailing segments to
+    # 0 rather than raising — the same live-and-let-live rule as split_ratio.
+    # Without a :rest, leftover space stays unassigned (no implicit stretch).
+    # Every constraint yields a Rect (possibly 0-sized), so destructuring is
+    # stable: `header, body, status = rect.split_rows(2, :rest, 2)`.
+    def split_rows(*constraints)
+      top = row
+      resolve_segments(constraints, rows).map do |size|
+        segment = Rect.new(row: top, col: col, rows: size, cols: cols)
+        top += size
+        segment
+      end
+    end
+
+    # Same as split_rows, but left to right over the columns.
+    def split_cols(*constraints)
+      left = col
+      resolve_segments(constraints, cols).map do |size|
+        segment = Rect.new(row: row, col: left, rows: rows, cols: size)
+        left += size
+        segment
+      end
+    end
+
     def shift_right(by)
       Rect.new(row: row, col: col + by, rows: rows, cols: cols - by)
     end
@@ -52,5 +87,39 @@ module TuiTui
 
       [with(cols: cols - width), Rect.new(row: row, col: col + cols - width, rows: rows, cols: width)]
     end
+
+    private
+
+    # Segment sizes for split_rows / split_cols: nominal sizes first (:rest
+    # from the leftover), then a front-to-back pass clamping each to what
+    # remains of `total`.
+    def resolve_segments(constraints, total)
+      rest_count = constraints.count(:rest)
+      claimed = constraints.sum { |constraint| nominal_size(constraint, total) }
+      base, spare = rest_count.zero? ? [0, 0] : [total - claimed, 0].max.divmod(rest_count)
+
+      rest_index = -1
+      remaining = total
+      constraints.map do |constraint|
+        size = if constraint == :rest
+                 rest_index += 1
+                 base + (rest_index < spare ? 1 : 0)
+               else
+                 nominal_size(constraint, total)
+               end
+        size = size.clamp(0, remaining)
+        remaining -= size
+        size
+      end
+    end
+
+    def nominal_size(constraint, total)
+      case constraint
+      when Integer then constraint
+      when Float then (total * constraint).round
+      when :rest then 0
+      else raise ArgumentError, "unknown layout constraint: #{constraint.inspect}"
+      end
+    end
   end
 end

data/lib/tui_tui/runtime.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "command"
 require_relative "screen"
 require_relative "render_context"
 
 module TuiTui
-  # Small Elm-style loop: render, read one event, fold it through the app, repeat.
+  # Small Elm-style loop: render, read one event, fold it through the app,
+  # repeat. `update` returns the next app, `[app, *commands]` to also request
+  # one-shot effects (see Command), or `:quit`/nil to stop; `[:quit, *commands]`
+  # performs the commands and then stops.
   class Runtime
     def initialize(app)
       @app = app
     end
 
+    # `tick:` is the TickEvent period in seconds: ticks arrive on that fixed
+    # cadence (between input events too), not after idle gaps.
     def run(input: $stdin, output: $stdout, depth: ColorDepth.detect, tick: 0.1, mouse: Screen.mouse_default, box: ENV["TUITUI_BOX"])
       Screen.run(input: input, output: output, depth: depth, mouse: mouse, box: box) do |screen|
         raise "tui_tui: not a terminal" if screen.nil?
@@ -18,19 +24,47 @@ module TuiTui
         loop do
           event = screen.events.next_event(tick: tick)
           break if event.is_a?(EofEvent)
-          next if inert_tick?(event)
 
-          screen.invalidate if wants_redraw?(event)
-          result = @app.update(event)
-          break if result == :quit || result.nil?
+          folded = Runtime.step(@app, event)
+          next if folded.nil?
 
-          @app = result
-          flush_clipboard(screen)
+          app, commands = folded
+          commands.each { |command| perform(command, screen) }
+          break if app.nil?
+
+          @app = app
+          flush_mouse(screen)
           screen.render(view(screen))
         end
       end
     end
 
+    # Normalizes the update result to [app, commands]; a quit (bare or as the
+    # array head) becomes a nil app. An app is never itself an Array. Shared
+    # with TestRuntime so both read `update`'s contract the same way.
+    def self.unwrap(result)
+      app, commands = result.is_a?(Array) ? [result.first, result.drop(1)] : [result, []]
+      [app == :quit ? nil : app, commands]
+    end
+
+    # The canonical pure part of one loop iteration: drop an inert tick
+    # (returning nil), otherwise fold the event through `update`, validate the
+    # requested commands, and return [next_app_or_nil, commands]. Runtime and
+    # TestRuntime both fold through this, so their semantics cannot drift.
+    def self.step(app, event)
+      return nil if inert_tick?(app, event)
+
+      app, commands = unwrap(app.update(event))
+      commands.each { |command| Command.validate!(command) }
+      [app, commands]
+    end
+
+    # Ticks are opt-in: a TickEvent is inert unless the app explicitly wants it
+    # (so a plain app like counter.rb never redraws on the timer).
+    def self.inert_tick?(app, event)
+      event.is_a?(TickEvent) && !(app.respond_to?(:wants_tick?) && app.wants_tick?)
+    end
+
     private
 
     # Pass a RenderContext (size + resolved chrome + canvas factory). It is
@@ -39,22 +73,20 @@ module TuiTui
       @app.view(RenderContext.new(size: screen.size, chrome: screen.chrome))
     end
 
-    def flush_clipboard(screen)
-      # Clipboard writes stay an effect of the loop, requested by the app.
-      return unless @app.respond_to?(:take_clipboard)
-
-      text = @app.take_clipboard
-      screen.copy(text) if text
+    def perform(command, screen)
+      case command
+      when Command::Copy then screen.copy(command.text)
+      when Command::Invalidate then screen.invalidate
+      else raise ArgumentError, "tui_tui: unknown command #{command.inspect}"
+      end
     end
 
-    def wants_redraw?(event)
-      @app.respond_to?(:redraw?) && @app.redraw?(event)
-    end
+    # Apps may release/recapture the mouse per frame (e.g. to allow a native
+    # terminal selection while a read-only pane is open).
+    def flush_mouse(screen)
+      return unless @app.respond_to?(:wants_mouse?)
 
-    def inert_tick?(event)
-      # Ticks are opt-in: a TickEvent is inert unless the app explicitly wants it
-      # (so a plain app like counter.rb never redraws on the timer).
-      event.is_a?(TickEvent) && !(@app.respond_to?(:wants_tick?) && @app.wants_tick?)
+      screen.mouse = @app.wants_mouse?
     end
   end
 end

data/lib/tui_tui/screen.rb

@@ -6,7 +6,7 @@ require_relative "ansi"
 require_relative "size"
 require_relative "color_depth"
 require_relative "box_chrome"
-require_relative "box_prober"
+require_relative "box_chrome_resolver"
 require_relative "canvas_compositor"
 require_relative "terminal_size"
 require_relative "event_stream"
@@ -52,11 +52,19 @@ module TuiTui
 
     attr_reader :events, :chrome
 
+    # Toggle mouse reporting mid-session (so an app can release the mouse for a
+    # native terminal selection while a read-only pane is open).
+    def mouse=(enabled)
+      @session.mouse = enabled
+    end
+
+    def mouse = @session.mouse
+
     def start
       @session.start
       # Probe box-drawing support once, after raw mode + alt screen, before the
       # first render/next_event so the DSR reply never reaches the key reader.
-      @chrome = BoxChrome.resolve(
+      @chrome = BoxChromeResolver.new.resolve(
         input: @input,
         output: @output,
         term_cols: size.cols,
@@ -71,7 +79,7 @@ module TuiTui
     # is appended only on a full repaint or when the cursor actually moved, so an
     # idle identical re-render still writes nothing.
     def render(canvas)
-      full = @previous.nil? || !@previous.same_size?(canvas)
+      full = full_repaint?(canvas)
       out = @compositor.render(@previous, canvas)
       out += cursor_directive(canvas) if full || canvas.cursor != @cursor
       @output.write(out)
@@ -93,6 +101,10 @@ module TuiTui
 
     private
 
+    def full_repaint?(canvas)
+      @previous.nil? || @previous.rows != canvas.rows || @previous.cols != canvas.cols
+    end
+
     def cursor_directive(canvas)
       pos = canvas.cursor
       pos ? Ansi.move(pos[0], pos[1]) + Ansi::SHOW : Ansi::HIDE

data/lib/tui_tui/terminal_session.rb

@@ -16,7 +16,8 @@ module TuiTui
     end
 
     def start
-      @console.raw!
+      # `intr: true` keeps the interrupt/quit/suspend characters live in raw mode, so Ctrl-C raises SIGINT.
+      @console.raw!(intr: true)
       @output.write(Ansi::ALT_ON + Ansi::HIDE + Ansi::CLEAR + (@mouse ? Ansi::MOUSE_ON : ""))
       @output.flush
       @prev_winch = trap("WINCH") { @events.resized! }
@@ -24,6 +25,20 @@ module TuiTui
       at_exit { close }
     end
 
+    attr_reader :mouse
+
+    # Toggle mouse reporting mid-session. Releasing it (false) lets the user
+    # make a native terminal selection (drag to select / copy) over the alternate
+    # screen; re-enabling restores in-app mouse events. No-op if unchanged.
+    def mouse=(enabled)
+      enabled = !!enabled
+      return if @closed || enabled == @mouse
+
+      @output.write(enabled ? Ansi::MOUSE_ON : Ansi::MOUSE_OFF)
+      @output.flush
+      @mouse = enabled
+    end
+
     def close
       # Close is called from ensure, at_exit, and signal traps.
       return if @closed