tui_tui 0.1.0

data/lib/tui_tui/runtime.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "screen"
+
+module TuiTui
+  # Small Elm-style loop: render, read one event, fold it through the app, repeat.
+  class Runtime
+    def initialize(app)
+      @app = app
+    end
+
+    def run(input: $stdin, output: $stdout, depth: ColorDepth.detect, tick: 0.1, mouse: Screen.mouse_default)
+      Screen.run(input: input, output: output, depth: depth, mouse: mouse) do |screen|
+        raise "tui_tui: not a terminal" if screen.nil?
+
+        screen.render(@app.view(screen.size))
+        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?
+
+          @app = result
+          flush_clipboard(screen)
+          screen.render(@app.view(screen.size))
+        end
+      end
+    end
+
+    private
+
+    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
+    end
+
+    def wants_redraw?(event)
+      @app.respond_to?(:redraw?) && @app.redraw?(event)
+    end
+
+    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?)
+    end
+  end
+end

data/lib/tui_tui/screen.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+require_relative "ansi"
+require_relative "size"
+require_relative "color_depth"
+require_relative "canvas_compositor"
+require_relative "terminal_size"
+require_relative "event_stream"
+require_relative "terminal_session"
+
+module TuiTui
+  # Terminal-facing screen owner: session lifecycle, event stream, and rendering.
+  class Screen
+    DEFAULT_SIZE = Size.new(rows: 24, cols: 80)
+
+    def self.run(input: $stdin, output: $stdout, depth: ColorDepth.detect, mouse: mouse_default)
+      console = IO.console
+      # Let callers provide a non-interactive fallback for piped output.
+      return yield(nil) if console.nil? || !output.tty?
+
+      screen = new(console, input, output, depth, mouse: mouse)
+      screen.start
+      begin
+        yield screen
+      ensure
+        screen.close
+      end
+    end
+
+    def self.mouse_default
+      !%w[0 off false].include?(ENV["TUITUI_MOUSE"])
+    end
+
+    def initialize(console, input, output, depth, mouse: true)
+      @output = output
+      @compositor = CanvasCompositor.new(depth: depth)
+      @term_size = TerminalSize.new(console, default: DEFAULT_SIZE)
+      @events = EventStream.new(input: input, size: @term_size)
+      @session = TerminalSession.new(console: console, output: output, events: @events, mouse: mouse)
+      @previous = nil
+      # the cursor position last written (the session starts it hidden)
+      @cursor = nil
+    end
+
+    attr_reader :events
+
+    def start = @session.start
+
+    def size = @term_size.size
+
+    # Render `canvas`: the compositor computes the (full or per-row diff) escape
+    # string, then the cursor is repositioned (or hidden). The cursor directive
+    # 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)
+      out = @compositor.render(@previous, canvas)
+      out += cursor_directive(canvas) if full || canvas.cursor != @cursor
+      @output.write(out)
+      @output.flush
+      @previous = canvas
+      @cursor = canvas.cursor
+    end
+
+    def invalidate
+      @previous = nil
+    end
+
+    def copy(text)
+      @output.write(Ansi.clipboard(text))
+      @output.flush
+    end
+
+    def close = @session.close
+
+    private
+
+    def cursor_directive(canvas)
+      pos = canvas.cursor
+      pos ? Ansi.move(pos[0], pos[1]) + Ansi::SHOW : Ansi::HIDE
+    end
+  end
+end

data/lib/tui_tui/scroll_list.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Cursor and viewport arithmetic shared by list-like widgets.
+  class ScrollList
+    attr_reader :cursor, :top
+
+    def initialize(count = 0)
+      @count = count
+      @cursor = 0
+      @top = 0
+    end
+
+    def count=(value)
+      @count = [value, 0].max
+      @cursor = @cursor.clamp(0, last)
+    end
+
+    attr_reader :count
+
+    def empty? = @count.zero?
+    def last = [@count - 1, 0].max
+    def at_end? = @cursor == last
+
+    def move(delta) = go_to(@cursor + delta)
+    def page(height) = move(height)
+    def to_top = go_to(0)
+    def to_end = go_to(last)
+
+    def go_to(index)
+      @cursor = index.clamp(0, last)
+      self
+    end
+
+    def ensure_visible(height)
+      return self if height <= 0
+
+      @top = @cursor if @cursor < @top
+      @top = @cursor - height + 1 if @cursor >= @top + height
+      @top = 0 if @top.negative?
+      self
+    end
+
+    def each_visible(height)
+      return enum_for(:each_visible, height) unless block_given?
+
+      height.times do |offset|
+        index = @top + offset
+        break if index >= @count
+
+        yield index, offset
+      end
+
+      self
+    end
+  end
+end

data/lib/tui_tui/scrollbar.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "rect"
+require_relative "style"
+require_relative "theme"
+
+module TuiTui
+  # A vertical scroll indicator for a 1-column gutter.
+  # It sizes a thumb from top/visible/total and draws ASCII-only chrome.
+  module Scrollbar
+    module_function
+
+    TRACK = Theme::DEFAULT.scroll_track
+    THUMB = Theme::DEFAULT.scroll_thumb
+
+    def draw(canvas, rect, top:, visible:, total:, track: "|", thumb: " ", track_style: TRACK, thumb_style: THUMB)
+      return canvas if rect.rows <= 0
+
+      length, offset = geometry(rect.rows, top, visible, total)
+      rect.rows.times do |i|
+        in_thumb = i >= offset && i < offset + length
+        canvas.text(rect.row + i, rect.col, in_thumb ? thumb : track, in_thumb ? thumb_style : track_style)
+      end
+
+      canvas
+    end
+
+    # The thumb's [length, offset] in rows for a `height`-row track. Returns
+    # [0, 0] (no thumb, track only) when everything fits — nothing to scroll.
+    def geometry(height, top, visible, total)
+      visible = [visible, 1].max
+      total = [total, visible].max
+      return [0, 0] if total <= visible
+
+      length = [(height * visible / total.to_f).round, 1].max.clamp(1, height)
+      offset = ((height - length) * top.to_f / (total - visible)).round
+      [length, offset.clamp(0, height - length)]
+    end
+  end
+end

data/lib/tui_tui/select.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+require_relative "style"
+require_relative "scroll_list"
+require_relative "list"
+require_relative "line"
+require_relative "span"
+require_relative "rect"
+require_relative "modal"
+require_relative "key_intent"
+
+module TuiTui
+  # 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 = 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)
+      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)
+      rect = @items_rect
+      return nil unless rect && event.col.between?(rect.col, rect.col + rect.cols - 1)
+
+      index = @list.top + (event.row - rect.row)
+      return nil unless (event.row - rect.row).between?(0, rect.rows - 1) && !@list.empty? && index <= @list.last
+
+      @list.go_to(index)
+      @list.cursor
+    end
+  end
+end

data/lib/tui_tui/size.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TuiTui
+  Size = Data.define(:rows, :cols)
+end

data/lib/tui_tui/span.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+
+module TuiTui
+  # A run of text sharing one Style.
+  # Width is terminal-column aware via DisplayText.
+  Span = Data.define(:text, :style) do
+    # Convenience constructor: Span["hi", style] (style optional).
+    def self.[](text, style = nil) = new(text: text.to_s, style: style)
+
+    def width = DisplayText.new(text).width
+  end
+end

data/lib/tui_tui/status_bar.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+
+module TuiTui
+  # A one-row status/footer bar.
+  # It draws left text from the start and optional right text flush right.
+  module StatusBar
+    module_function
+
+    def draw(canvas, rect, left: "", right: nil, style: nil)
+      canvas.fill(rect, style)
+
+      right_width = right ? DisplayText.new(right).width : 0
+      fits_right = right && right_width < rect.cols
+      left_max = fits_right ? rect.cols - right_width : rect.cols
+
+      canvas.text(rect.row, rect.col, DisplayText.new(left).truncate(left_max), style)
+      canvas.text(rect.row, rect.col + rect.cols - right_width, right, style) if fits_right
+      canvas
+    end
+  end
+end

data/lib/tui_tui/style.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "palette"
+
+module TuiTui
+  # Value object for SGR styling. It downgrades richer colors to the selected
+  # terminal depth instead of emitting unsupported escape sequences.
+  class Style
+    NAMED = {
+      black: 30,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      white: 37,
+      bright_black: 90,
+      bright_red: 91,
+      bright_green: 92,
+      bright_yellow: 93,
+      bright_blue: 94,
+      bright_magenta: 95,
+      bright_cyan: 96,
+      bright_white: 97
+    }.freeze
+
+    ATTRS = {bold: 1, dim: 2, italic: 3, underline: 4, reverse: 7}.freeze
+
+    attr_reader :fg, :bg, :attrs
+
+    def initialize(fg: nil, bg: nil, attrs: [])
+      @fg = fg
+      @bg = bg
+      @attrs = attrs
+      @palette = Palette.new
+    end
+
+    def with(fg: @fg, bg: @bg, attrs: @attrs)
+      self.class.new(fg: fg, bg: bg, attrs: attrs)
+    end
+
+    def ==(other)
+      # Canvas diffing relies on equivalent styles comparing equal.
+      other.is_a?(Style) && fg == other.fg && bg == other.bg && attrs == other.attrs
+    end
+
+    alias_method :eql?, :==
+
+    def hash = [fg, bg, attrs].hash
+
+    def paint(text, depth: :ansi256, enabled: true)
+      return text if !enabled || depth == :none
+
+      codes = sgr_codes(depth)
+      return text if codes.empty?
+
+      "\e[#{codes.join(";")}m#{text}\e[0m"
+    end
+
+    def sgr_codes(depth)
+      codes = @attrs.map { |attr| ATTRS.fetch(attr) }
+      codes.concat(color_codes(@fg, depth, ground: :fg))
+      codes.concat(color_codes(@bg, depth, ground: :bg))
+      codes
+    end
+
+    private
+
+    def color_codes(color, depth, ground:)
+      case color
+      when nil
+        []
+      when Symbol
+        [ground_offset(NAMED.fetch(color), ground)]
+      when Integer
+        integer_codes(color, depth, ground)
+      when Array
+        array_codes(color, depth, ground)
+      else
+        []
+      end
+    end
+
+    def integer_codes(index, depth, ground)
+      return [ground_offset(@palette.nearest_code(@palette.rgb_from_256(index)), ground)] if depth == :basic16
+
+      [ground == :bg ? 48 : 38, 5, index]
+    end
+
+    def array_codes(rgb, depth, ground)
+      return [ground_offset(@palette.nearest_code(rgb), ground)] if depth == :basic16
+      # RGB has no honest representation below truecolor except the basic16 path.
+      return [] unless depth == :truecolor
+
+      [ground == :bg ? 48 : 38, 2, *rgb]
+    end
+
+    def ground_offset(base, ground) = ground == :bg ? base + 10 : base
+  end
+end

data/lib/tui_tui/terminal_session.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "ansi"
+
+module TuiTui
+  # Owns raw mode, alternate screen, and restoration traps for one TUI session.
+  class TerminalSession
+    RESTORE_SIGNALS = %w[TERM HUP INT].freeze
+
+    def initialize(console:, output:, events:, mouse:)
+      @console = console
+      @output = output
+      @events = events
+      @mouse = mouse
+      @closed = false
+    end
+
+    def start
+      @console.raw!
+      @output.write(Ansi::ALT_ON + Ansi::HIDE + Ansi::CLEAR + (@mouse ? Ansi::MOUSE_ON : ""))
+      @output.flush
+      @prev_winch = trap("WINCH") { @events.resized! }
+      install_restore_traps
+      at_exit { close }
+    end
+
+    def close
+      # Close is called from ensure, at_exit, and signal traps.
+      return if @closed
+
+      @closed = true
+      @output.write((@mouse ? Ansi::MOUSE_OFF : "") + Ansi::SHOW + Ansi::ALT_OFF)
+      @output.flush
+      begin
+        @console.cooked!
+      rescue StandardError
+        nil
+      end
+
+      trap("WINCH", @prev_winch || "DEFAULT") if defined?(@prev_winch)
+      restore_signal_traps
+    end
+
+    private
+
+    def install_restore_traps
+      @prev_signals = {}
+      RESTORE_SIGNALS.each do |signal|
+        @prev_signals[signal] = trap(signal) do
+          # Restore the terminal, then preserve the signal's normal process effect.
+          close
+          trap(signal, "DEFAULT")
+          Process.kill(signal, Process.pid)
+        end
+      rescue ArgumentError
+      end
+    end
+
+    def restore_signal_traps
+      @prev_signals&.each { |signal, handler| trap(signal, handler || "DEFAULT") }
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/tui_tui/terminal_size.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "size"
+
+module TuiTui
+  # Reads winsize with a fallback that keeps layout deterministic in tests and PTYs.
+  class TerminalSize
+    DEFAULT = Size.new(rows: 24, cols: 80)
+
+    def initialize(console, default: DEFAULT)
+      @console = console
+      @default = default
+    end
+
+    def size
+      rows, cols = @console.winsize
+      return @default if rows.to_i.zero? || cols.to_i.zero?
+
+      Size.new(rows: rows, cols: cols)
+    rescue StandardError
+      @default
+    end
+  end
+end

data/lib/tui_tui/text_sanitizer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Normalizes text before rendering so malformed input bytes are displayed
+  # safely instead of raising encoding errors.
+  module TextSanitizer
+    module_function
+
+    def sanitize(string)
+      string.valid_encoding? ? string : string.scrub("?")
+    end
+  end
+end

data/lib/tui_tui/text_view.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "line"
+require_relative "span"
+require_relative "scrollbar"
+
+module TuiTui
+  # A scrolled read-only text window.
+  # Lines may be Strings, Lines, or Span arrays, supplied eagerly or lazily.
+  module TextView
+    module_function
+
+    def draw(canvas, rect, lines = nil, top: 0, style: nil, scrollbar: nil, total: nil)
+      body, gutter = scrollbar ? rect.split_gutter : [rect, nil]
+      body.rows.times do |offset|
+        index = top + offset
+        content = lines ? lines[index] : yield(index)
+        next if content.nil?
+
+        canvas.line(body.row + offset, body.col, as_line(content, style).truncate(body.cols))
+      end
+
+      draw_scrollbar(canvas, gutter, top, total || lines&.length, body.rows, scrollbar) if gutter
+      canvas
+    end
+
+    def draw_scrollbar(canvas, gutter, top, total, visible, theme)
+      return unless total
+
+      Scrollbar.draw(
+        canvas,
+        gutter,
+        top: top,
+        visible: visible,
+        total: total,
+        track_style: theme.scroll_track,
+        thumb_style: theme.scroll_thumb
+      )
+    end
+
+    def as_line(content, style)
+      case content
+      when Line
+        content
+      when Array
+        Line.new(content)
+      else
+        Line[Span[content.to_s, style]]
+      end
+    end
+  end
+end