tui_tui 0.1.0

data/lib/tui_tui/help.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+require_relative "style"
+require_relative "modal"
+
+module TuiTui
+  # 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

data/lib/tui_tui/key_code.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TuiTui
+  module KeyCode
+    ESCAPE = "\e"
+    CTRL_C = "\u0003"
+    BACKSPACE = "\u007F"
+  end
+end

data/lib/tui_tui/key_intent.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "key_code"
+
+module TuiTui
+  # Shared navigation intent mapping for widgets.
+  class KeyIntent
+    NAVIGATION = {
+      :up => :up,
+      "k" => :up,
+      :down => :down,
+      "j" => :down,
+      :home => :top,
+      "g" => :top,
+      :end => :bottom,
+      "G" => :bottom
+    }.freeze
+
+    CANCEL = [:escape, "q", KeyCode::CTRL_C].freeze
+
+    def self.for(key) = new.for(key)
+
+    def for(key)
+      return :cancel if CANCEL.include?(key)
+
+      NAVIGATION[key]
+    end
+  end
+end

data/lib/tui_tui/key_reader.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "event"
+require_relative "key_code"
+
+module TuiTui
+  # Decodes raw-mode terminal input into literal keys, named keys, and mouse events.
+  class KeyReader
+    ESCAPES = {
+      "\e[A" => :up,
+      "\e[B" => :down,
+      "\e[C" => :right,
+      "\e[D" => :left,
+      "\eOA" => :up,
+      "\eOB" => :down,
+      "\eOC" => :right,
+      "\eOD" => :left,
+      "\e[H" => :home,
+      "\e[F" => :end,
+      "\eOH" => :home,
+      "\eOF" => :end,
+      "\e[1~" => :home,
+      "\e[4~" => :end,
+      "\e[5~" => :pgup,
+      "\e[6~" => :pgdn,
+      "\e[3~" => :delete,
+      "\e[Z" => :backtab
+    }.freeze
+
+    ESCAPE_TAIL_BYTES = 256
+
+    # SGR mouse reports can grow with coordinate length; decode the first report
+    # if several drag reports arrive in one non-blocking read.
+    MOUSE = /\A\[<(\d+);(\d+);(\d+)([Mm])/.freeze
+    MOUSE_MOTION = 0x20
+    MOUSE_WHEEL = 0x40
+
+    # A modified special key arrives as a CSI with a "1;<mod>" parameter, e.g.
+    # Ctrl+Right = "\e[1;5C", Shift+Up = "\e[1;2A", Ctrl+Delete = "\e[3;5~".
+    # MOD encodes the held modifiers as (1 + Shift(1) + Alt(2) + Ctrl(4)).
+    MODIFIED = /\A\[(\d*);(\d+)([A-Za-z~])/.freeze
+    MOD_LETTER = {"A" => :up, "B" => :down, "C" => :right, "D" => :left, "H" => :home, "F" => :end}.freeze
+    MOD_TILDE = {1 => :home, 3 => :delete, 4 => :end, 5 => :pgup, 6 => :pgdn, 7 => :home, 8 => :end}.freeze
+    MOD_BITS = {shift: 1, alt: 2, ctrl: 4}.freeze
+
+    # One keypress/event from `io` (String, Symbol, or MouseEvent), nil at EOF.
+    def read(io) = read_all(io)&.first
+
+    def read_all(io)
+      first = io.getch
+      return nil if first.nil?
+      return decode_escape_events(read_escape_tail(io)) if first == KeyCode::ESCAPE
+      return [assemble_utf8(io, first)] if first.bytesize == 1 && first.getbyte(0) >= 0x80
+
+      [first]
+    end
+
+    def decode_escape(rest)
+      return :escape if rest.nil? || rest.empty?
+
+      mouse = decode_mouse(rest)
+      return mouse if mouse
+
+      modified = decode_modified(rest)
+      return modified if modified
+
+      ESCAPES["\e" + rest] || :escape
+    end
+
+    # Decode a whole ESC tail into events, batching consecutive mouse reports
+    # (and otherwise yielding a single key/escape).
+    def decode_escape_events(rest)
+      return [:escape] if rest.nil? || rest.empty?
+
+      mice = []
+      remainder = rest
+      loop do
+        remainder = remainder.sub(/\A\e/, "")
+        match = MOUSE.match(remainder) or break
+
+        mice << mouse_event_from(match)
+        remainder = match.post_match
+      end
+
+      mice.empty? ? [decode_escape(rest)] : mice
+    end
+
+    private
+
+    def decode_modified(rest)
+      match = MODIFIED.match(rest)
+      return nil unless match
+
+      final = match[3]
+      base = final == "~" ? MOD_TILDE[match[1].to_i] : MOD_LETTER[final]
+      return nil unless base
+
+      prefix = modifier_prefix(match[2].to_i)
+      return nil unless prefix
+
+      prefix.empty? ? base : :"#{prefix}_#{base}"
+    end
+
+    # "ctrl", "shift", "ctrl_shift", ... for an xterm modifier parameter, "" for
+    # no modifiers, or nil when the value is out of range.
+    def modifier_prefix(mod)
+      bits = mod - 1
+      return nil if bits.negative? || bits > 7
+
+      %i[ctrl alt shift].select { |name| bits.anybits?(MOD_BITS[name]) }.join("_")
+    end
+
+    def read_escape_tail(io)
+      rest = io.read_nonblock(ESCAPE_TAIL_BYTES, exception: false)
+      rest.is_a?(String) ? rest : nil
+    end
+
+    def assemble_utf8(io, lead)
+      # Raw mode may deliver multibyte input one byte at a time.
+      bytes = +lead.b
+      utf8_continuation_count(lead.getbyte(0)).times do
+        nxt = io.read_nonblock(1, exception: false)
+        break unless nxt.is_a?(String) && !nxt.empty?
+
+        bytes << nxt
+      end
+
+      char = bytes.force_encoding("UTF-8")
+      char.valid_encoding? ? char : :unknown
+    end
+
+    def utf8_continuation_count(byte)
+      return 1 if byte.between?(0xC0, 0xDF)
+      return 2 if byte.between?(0xE0, 0xEF)
+      return 3 if byte.between?(0xF0, 0xF7)
+
+      0
+    end
+
+    def decode_mouse(rest)
+      match = MOUSE.match(rest)
+      match && mouse_event_from(match)
+    end
+
+    def mouse_event_from(match)
+      mouse_event(match[1].to_i, match[2].to_i, match[3].to_i, match[4] == "m")
+    end
+
+    def mouse_event(flags, col, row, released)
+      if flags & MOUSE_WHEEL != 0
+        button = (flags & 0b1).zero? ? :wheel_up : :wheel_down
+        MouseEvent.new(action: :wheel, button: button, col: col, row: row)
+      elsif flags & MOUSE_MOTION != 0
+        MouseEvent.new(action: :drag, button: button_name(flags), col: col, row: row)
+      elsif released
+        MouseEvent.new(action: :release, button: button_name(flags), col: col, row: row)
+      else
+        MouseEvent.new(action: :press, button: button_name(flags), col: col, row: row)
+      end
+    end
+
+    def button_name(flags)
+      case flags & 0b11
+      when 0
+        :left
+      when 1
+        :middle
+      when 2
+        :right
+      else
+        :none
+      end
+    end
+  end
+end

data/lib/tui_tui/line.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "span"
+require_relative "display_text"
+
+module TuiTui
+  # An ordered list of styled Spans.
+  # Width-aware truncation preserves each span's style.
+  class Line
+    # Convenience constructor: Line[Span["a", s1], Span["b", s2]].
+    def self.[](*spans) = new(spans)
+
+    def initialize(spans = [])
+      @spans = spans
+    end
+
+    attr_reader :spans
+
+    def width = @spans.sum(&:width)
+    def each(&block) = @spans.each(&block)
+    def to_s = @spans.map(&:text).join
+
+    # Truncate to `max` columns, keeping span styles. When content is dropped,
+    # `marker` is appended in the style of the span it cut into; the marker's own
+    # width is reserved so the result never exceeds `max`.
+    def truncate(max, marker: "...")
+      return self if width <= max
+
+      budget = max - DisplayText.new(marker).width
+      if budget <= 0
+        clipped = DisplayText.new(marker).truncate(max, marker: "").to_s
+        return self.class.new([Span[clipped, @spans.first&.style]])
+      end
+
+      take_until(budget, marker)
+    end
+
+    private
+
+    def take_until(budget, marker)
+      kept = []
+      used = 0
+      @spans.each do |span|
+        if used + span.width <= budget
+          kept << span
+          used += span.width
+          next
+        end
+
+        room = budget - used
+        kept << Span[DisplayText.new(span.text).truncate(room, marker: "").to_s, span.style] if room.positive?
+        kept << Span[marker, (kept.last || span).style]
+        break
+      end
+
+      self.class.new(kept)
+    end
+  end
+end

data/lib/tui_tui/list.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "rect"
+require_relative "line"
+require_relative "scrollbar"
+
+module TuiTui
+  # Drawing companion for ScrollList.
+  # Row content comes from the caller, keeping the list domain-agnostic.
+  class List
+    def initialize(scroll)
+      @scroll = scroll
+    end
+
+    def draw(canvas, rect, highlight: nil, scrollbar: nil)
+      body, gutter = scrollbar ? rect.split_gutter : [rect, nil]
+      @scroll.ensure_visible(body.rows)
+      @scroll.each_visible(body.rows) do |index, offset|
+        row = body.row + offset
+        selected = index == @scroll.cursor
+        canvas.fill(Rect.new(row: row, col: body.col, rows: 1, cols: body.cols), highlight) if highlight && selected
+        canvas.line(row, body.col, as_line(yield(index, selected)).truncate(body.cols))
+      end
+
+      draw_scrollbar(canvas, gutter, scrollbar) if gutter
+      canvas
+    end
+
+    private
+
+    def draw_scrollbar(canvas, gutter, theme)
+      Scrollbar.draw(
+        canvas,
+        gutter,
+        top: @scroll.top,
+        visible: gutter.rows,
+        total: @scroll.count,
+        track_style: theme.scroll_track,
+        thumb_style: theme.scroll_thumb
+      )
+    end
+
+    def as_line(content) = content.is_a?(Line) ? content : Line.new(Array(content))
+  end
+end

data/lib/tui_tui/modal.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "rect"
+require_relative "theme"
+
+module TuiTui
+  # Base protocol and shared centered-panel framing for overlay widgets.
+  class Modal
+    PAD = 2
+
+    def handle(_key) = raise NotImplementedError, "#{self.class}#handle"
+
+    # Optional mouse handling, same return contract as #handle (resolved value,
+    # or nil to stay open). Default no-op so widgets opt in only as needed; the
+    # host routes MouseEvents here and KeyEvents to #handle.
+    def handle_mouse(_event) = nil
+
+    def draw(_canvas, _size) = raise NotImplementedError, "#{self.class}#draw"
+
+    private
+
+    def theme = @theme || Theme::DEFAULT
+
+    def panel(canvas, inner:, body_rows:)
+      rect = Rect.centered(canvas, cols: inner + (PAD * 2) + 2, rows: body_rows + 2)
+      canvas.frame(rect, style: theme.frame)
+      [rect, rect.col + PAD + 1]
+    end
+  end
+end

data/lib/tui_tui/pager.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+require_relative "style"
+require_relative "rect"
+require_relative "modal"
+require_relative "key_intent"
+
+module TuiTui
+  # Scrollable read-only text modal.
+  class Pager < Modal
+    MARGIN = 2
+    WHEEL = 3
+
+    def initialize(title, lines, start: 0, close_keys: [], theme: Theme::DEFAULT)
+      @title = title
+      @lines = lines.map { |line| DisplayText.new(line) }
+      @top = start
+      @page = 1
+      @close_keys = close_keys
+      @theme = theme
+    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.text(rect.row + 3 + offset, rect.col + 2, line.truncate(inner), theme.muted)
+      end
+
+      canvas
+    end
+
+    private
+
+    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

data/lib/tui_tui/palette.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Color math for downgrading 256-color and RGB values to ANSI-16.
+  class Palette
+    ANSI16 = [
+      [[0, 0, 0], 30],
+      [[205, 0, 0], 31],
+      [[0, 205, 0], 32],
+      [[205, 205, 0], 33],
+      [[0, 0, 238], 34],
+      [[205, 0, 205], 35],
+      [[0, 205, 205], 36],
+      [[229, 229, 229], 37],
+      [[127, 127, 127], 90],
+      [[255, 0, 0], 91],
+      [[0, 255, 0], 92],
+      [[255, 255, 0], 93],
+      [[92, 92, 255], 94],
+      [[255, 0, 255], 95],
+      [[0, 255, 255], 96],
+      [[255, 255, 255], 97]
+    ].freeze
+
+    def nearest_code(rgb)
+      ANSI16.min_by { |color, _code| distance(color, rgb) }.last
+    end
+
+    def rgb_from_256(index)
+      return ANSI16[index].first if index < 16
+
+      if index <= 231
+        i = index - 16
+        [cube(i / 36), cube((i % 36) / 6), cube(i % 6)]
+      else
+        v = 8 + (10 * (index - 232))
+        [v, v, v]
+      end
+    end
+
+    private
+
+    def cube(step) = step.zero? ? 0 : (55 + (40 * step))
+
+    def distance(a, b)
+      (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2
+    end
+  end
+end

data/lib/tui_tui/prompt.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+require_relative "style"
+require_relative "modal"
+require_relative "key_code"
+
+module TuiTui
+  # 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)
+      @graphemes = value.grapheme_clusters
+      @pos = @graphemes.length
+      @theme = theme
+    end
+
+    def value = @graphemes.join
+
+    def handle(key)
+      case key
+      when "\r"
+        [:ok, value]
+      when :escape, KeyCode::CTRL_C
+        :cancel
+      when KeyCode::BACKSPACE, :backspace
+        edit { delete_back }
+      when :delete
+        edit { delete_forward }
+      when :left
+        edit { @pos = [@pos - 1, 0].max }
+      when :right
+        edit { @pos = [@pos + 1, @graphemes.length].min }
+      when :home
+        edit { @pos = 0 }
+      when :end
+        edit { @pos = @graphemes.length }
+      when String
+        edit { insert(key) if printable?(key) }
+      end
+    end
+
+    def handle_mouse(event)
+      return nil unless event.action == :press && @text_row == event.row
+
+      edit { @pos = index_at(event.col - @text_col) }
+    end
+
+    def draw(canvas, size)
+      inner = [MIN_INNER, @label.width + 1 + DisplayText.new(value).width].max
+      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
+      canvas.text(@text_row, @text_col, value, theme.text)
+      draw_cursor(canvas, @text_row, @text_col)
+      canvas
+    end
+
+    private
+
+    def edit
+      yield
+      nil
+    end
+
+    # Grapheme index whose left edge is closest to `rel` columns into the value.
+    def index_at(rel)
+      return 0 if rel <= 0
+
+      width = 0
+      @graphemes.each_with_index do |grapheme, i|
+        w = DisplayText.new(grapheme).width
+        return i if rel < width + ((w + 1) / 2)
+
+        width += w
+      end
+
+      @graphemes.length
+    end
+
+    def draw_cursor(canvas, row, text_col)
+      cursor_col = text_col + DisplayText.new(@graphemes[0...@pos].join).width
+      canvas.text(row, cursor_col, @graphemes[@pos] || " ", theme.cursor)
+    end
+
+    def insert(string)
+      head = @graphemes[0...@pos].join
+      @graphemes = (head + string + @graphemes[@pos..].join).grapheme_clusters
+      @pos = (head + string).grapheme_clusters.length
+    end
+
+    def delete_back
+      return if @pos.zero?
+
+      @graphemes.delete_at(@pos - 1)
+      @pos -= 1
+    end
+
+    def delete_forward
+      @graphemes.delete_at(@pos) if @pos < @graphemes.length
+    end
+
+    def printable?(string)
+      string.bytes.all? { |byte| byte >= 0x20 && byte != 0x7F }
+    end
+  end
+end

data/lib/tui_tui/rect.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # A 1-origin screen rectangle with pure layout helpers.
+  Rect = Data.define(:row, :col, :rows, :cols) do
+    def self.centered(within, cols:, rows:)
+      new(
+        row: [((within.rows - rows) / 2) + 1, 1].max,
+        col: [((within.cols - cols) / 2) + 1, 1].max,
+        rows: rows,
+        cols: 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)
+      [top, bottom]
+    end
+
+    def split_v(left_cols)
+      left = Rect.new(row: row, col: col, rows: rows, cols: left_cols)
+      right = Rect.new(row: row, col: col + left_cols, rows: rows, cols: cols - left_cols)
+      [left, right]
+    end
+
+    # Split into [left, right] by `ratio` of the width
+    def split_ratio(ratio, min: 0, gutter: 0)
+      lo = min
+      hi = cols - min - gutter
+      left_cols = hi < lo ? cols / 2 : (cols * ratio).round.clamp(lo, hi)
+      left, right = split_v(left_cols)
+      [left, right.shift_right(gutter)]
+    end
+
+    def shift_right(by)
+      Rect.new(row: row, col: col + by, rows: rows, cols: cols - by)
+    end
+
+    # Carve `width` columns off the right edge for a scrollbar gutter. Returns
+    # [body, gutter]; gutter is nil when the rect is too narrow to spare them.
+    def split_gutter(width = 1)
+      return [self, nil] if cols <= width
+
+      [with(cols: cols - width), Rect.new(row: row, col: col + cols - width, rows: rows, cols: width)]
+    end
+  end
+end