tui_tui 0.1.0

data/examples/widgets.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# A gallery of the built-in TuiTui widgets (Confirm / Select / Prompt / Help)
+# driven as modal overlays. The host keeps one modal while open, routes keys to
+# its `handle`, draws it over its own frame, and interprets the resolved value —
+# the same pattern any TuiTui app uses. The main screen shows the last result.
+# Press `t` to cycle the theme; the gallery text and the next modal follow it.
+#
+#   ruby examples/widgets.rb
+#
+# Keys: c confirm, s select, p prompt, ? help, t theme, q (or Ctrl-C) quit.
+
+require_relative "../lib/tui_tui"
+
+module WidgetsSample
+  THEMES = %i[cool warm mono].freeze
+
+  ITEMS = ["Red", "Green", "Blue", "日本語の項目", "Yellow"].freeze
+  HELP = [
+    ["c", "open a confirm dialog"],
+    ["s", "open a select list"],
+    ["p", "open a text prompt"],
+    ["t", "cycle theme (cool / warm / mono, follows light/dark)"],
+    ["?", "this help"],
+    ["q", "quit"],
+  ].freeze
+
+  class Gallery
+    def initialize
+      @last = "(nothing yet)"
+      @modal = nil
+      @on_result = nil
+      @theme_i = 0
+      @theme = TuiTui::Theme.auto(hue: THEMES[@theme_i])
+    end
+
+    def update(event)
+      case event
+      when TuiTui::MouseEvent then @modal ? route_modal_mouse(event) : self
+      when TuiTui::KeyEvent
+        return route_modal(event.key) if @modal
+
+        handle_key(event.key)
+      else self
+      end
+    end
+
+    def view(size)
+      canvas = TuiTui::Canvas.blank(size)
+      canvas.text(2, 3, "TuiTui widget gallery", @theme.title)
+      canvas.text(4, 3, "theme: #{THEMES[@theme_i]}", @theme.accent)
+      canvas.text(5, 3, "last result: #{@last}", @theme.text)
+      canvas.text(7, 3, "c confirm   s select   p prompt   ? help   t theme   q quit", @theme.muted)
+      @modal&.draw(canvas, size) # modal overlays the main screen
+      canvas
+    end
+
+    private
+
+    def handle_key(key)
+      case key
+      when "q", TuiTui::KeyCode::CTRL_C then return :quit
+      when "c" then open(TuiTui::Confirm.new("Proceed?", theme: @theme)) { |r| @last = "confirm -> #{r}" }
+      when "s" then open(TuiTui::Select.new("Pick a color", ITEMS, theme: @theme)) { |r| @last = "select -> #{label(r)}" }
+      when "p" then open(TuiTui::Prompt.new("Name:", theme: @theme)) { |r| @last = "prompt -> #{prompt_value(r)}" }
+      when "?" then open(TuiTui::Help.new("Keys", HELP, theme: @theme)) { nil }
+      when "t" then cycle_theme
+      end
+      self
+    end
+
+    def cycle_theme
+      @theme_i = (@theme_i + 1) % THEMES.size
+      @theme = TuiTui::Theme.auto(hue: THEMES[@theme_i])
+    end
+
+    def open(widget, &on_result)
+      @modal = widget
+      @on_result = on_result
+    end
+
+    def route_modal(key) = resolve_modal(@modal.handle(key))
+    def route_modal_mouse(event) = resolve_modal(@modal.handle_mouse(event))
+
+    def resolve_modal(result)
+      return self if result.nil? # still open
+
+      @modal = nil
+      @on_result.call(result)
+      self
+    end
+
+    def label(result) = result.is_a?(Integer) ? ITEMS[result] : result
+    def prompt_value(result) = result.is_a?(Array) ? result[1].inspect : result
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  TuiTui::Runtime.new(WidgetsSample::Gallery.new).run
+end

data/lib/tui_tui/ansi.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Raw VT/ANSI escape sequences as plain strings.
+  module Ansi
+    # enter alternate screen buffer
+    ALT_ON = "\e[?1049h"
+    # leave it, restoring the user's scrollback
+    ALT_OFF = "\e[?1049l"
+    # hide the cursor
+    HIDE = "\e[?25l"
+    # show it again
+    SHOW = "\e[?25h"
+    # clear the whole screen
+    CLEAR = "\e[2J"
+    # clear the current line
+    CLEAR_LINE = "\e[2K"
+    # move to row 1, col 1
+    HOME = "\e[H"
+    # reset all SGR attributes
+    RESET = "\e[0m"
+
+    # Mouse reporting:
+    # 1002 = button-event tracking
+    # 1006 = SGR extended coordinates
+    MOUSE_ON = "\e[?1002h\e[?1006h"
+    MOUSE_OFF = "\e[?1006l\e[?1002l"
+
+    def self.move(row, col) = "\e[#{row};#{col}H"
+
+    # OSC 52: set the terminal clipboard to `text` (base64-encoded).
+    def self.clipboard(text) = "\e]52;c;#{[text].pack("m0")}\a"
+  end
+end

data/lib/tui_tui/canvas.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative "width"
+require_relative "text_sanitizer"
+require_relative "display_text"
+require_relative "style"
+require_relative "cell"
+
+module TuiTui
+  # Pure drawing surface. Coordinates are 1-origin to match terminal cursor
+  # addressing, and text layout is terminal-column aware.
+  class Canvas
+    # Control bytes are rendered visibly instead of being emitted to the terminal.
+    CONTROL_GLYPH = "?"
+    FRAME = Style.new(fg: :bright_black)
+
+    def self.blank(size)
+      new(size.rows, size.cols)
+    end
+
+    attr_reader :rows, :cols
+    attr_reader :cursor
+
+    def initialize(rows, cols)
+      @rows = rows
+      @cols = cols
+      @grid = Array.new(rows) { Array.new(cols, Cell::BLANK) }
+      @cursor = nil
+    end
+
+    def cursor_at(row, col)
+      @cursor = [row, col] if row.between?(1, @rows) && col.between?(1, @cols)
+      self
+    end
+
+    def cell(row, col)
+      return nil unless row.between?(1, @rows) && col.between?(1, @cols)
+
+      @grid[row - 1][col - 1]
+    end
+
+    def text(row, col, string, style = nil)
+      return self unless row.between?(1, @rows)
+
+      column = col
+      TextSanitizer.sanitize(string.to_s).each_grapheme_cluster do |grapheme|
+        if Width.control?(grapheme.ord)
+          break if column > @cols
+
+          place(row, column, Cell.new(char: CONTROL_GLYPH, style: style))
+          column += 1
+          next
+        end
+
+        width = Width.cluster(grapheme)
+        # Leading combining marks have no base cell to attach to.
+        next if width.zero?
+
+        break if column > @cols
+        # Do not split a wide glyph across the right edge.
+        break if width == 2 && column == @cols
+
+        place(row, column, Cell.new(char: grapheme, style: style))
+        place(row, column + 1, Cell.new(char: nil, style: style)) if width == 2
+        column += width
+      end
+
+      self
+    end
+
+    def line(row, col, spans)
+      column = col
+      spans.each do |span|
+        text(row, column, span.text, span.style)
+        column += DisplayText.new(span.text).width
+      end
+
+      self
+    end
+
+    def fill(rect, style, char = " ")
+      cell = Cell.new(char: fill_char(char), style: style)
+      rect.rows.times do |dr|
+        row = rect.row + dr
+        rect.cols.times { |dc| place(row, rect.col + dc, cell) }
+      end
+
+      self
+    end
+
+    def hline(row, col, len, char = "-", style = nil)
+      text(row, col, char * len, style)
+    end
+
+    def frame(rect, style: FRAME)
+      fill(rect, nil)
+      bar = "+#{"-" * (rect.cols - 2)}+"
+      text(rect.row, rect.col, bar, style)
+      text(rect.row + rect.rows - 1, rect.col, bar, style)
+      (1...(rect.rows - 1)).each do |dy|
+        text(rect.row + dy, rect.col, "|", style)
+        text(rect.row + dy, rect.col + rect.cols - 1, "|", style)
+      end
+
+      self
+    end
+
+    def same_row?(other, r)
+      grid_row(r) == other.grid_row(r)
+    end
+
+    def same_size?(other)
+      @rows == other.rows && @cols == other.cols
+    end
+
+    # The changed column span of row `r` versus `other`, as [from, to] (1-origin,
+    # inclusive), or nil if the row is identical. The start is backed up off any
+    # wide-char continuation cell so a partial repaint never begins mid-glyph.
+    # Used by the compositor to repaint only the part of a row that moved.
+    def changed_span(other, r)
+      mine = grid_row(r)
+      theirs = other.grid_row(r)
+      first = last = nil
+      mine.each_index do |i|
+        next if mine[i] == theirs[i]
+
+        first ||= i
+        last = i
+      end
+
+      return nil if first.nil?
+
+      first -= 1 while first.positive? && mine[first].continuation?
+      [first + 1, last + 1]
+    end
+
+    # Render row `r`, or just the column span [from, to], coalescing same-styled
+    # runs and skipping wide-char continuation cells.
+    def render_row(r, from: 1, to: @cols, depth: :ansi256, enabled: true)
+      out = +""
+      run = +""
+      run_style = :none
+      grid_row(r)[(from - 1)..(to - 1)].each do |c|
+        next if c.continuation?
+
+        if run_style != :none && run_style != c.style
+          out << paint(run, run_style, depth, enabled)
+          run = +""
+        end
+
+        run_style = c.style
+        run << c.char
+      end
+
+      out << paint(run, run_style, depth, enabled) unless run.empty?
+      out
+    end
+
+    def grid_row(r) = @grid[r - 1]
+
+    private
+
+    # A fill glyph with any control bytes replaced by CONTROL_GLYPH, so `fill`
+    # upholds the same "Canvas never emits a raw control byte" guarantee as
+    # `text` (cheap: computed once per fill, not per cell).
+    def fill_char(char)
+      char.to_s.each_char.map { |c| Width.control?(c.ord) ? CONTROL_GLYPH : c }.join
+    end
+
+    def place(row, col, cell)
+      return unless row.between?(1, @rows) && col.between?(1, @cols)
+
+      grid_row = @grid[row - 1]
+      # Overwriting one half of a wide glyph orphans the other; blank it so the
+      # row keeps its column count (no stale continuation, no half-glyph).
+      grid_row[col] = Cell::BLANK if col < @cols && grid_row[col].continuation?
+      grid_row[col - 2] = Cell::BLANK if col >= 2 && grid_row[col - 1].continuation?
+      grid_row[col - 1] = cell
+    end
+
+    def paint(text, style, depth, enabled)
+      return text if style.nil? || style == :none
+
+      style.paint(text, depth: depth, enabled: enabled)
+    end
+  end
+end

data/lib/tui_tui/canvas_compositor.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "ansi"
+
+module TuiTui
+  # Builds the terminal update string.
+  # Same-size frames repaint only changed column spans of changed rows.
+  class CanvasCompositor
+    def initialize(depth: :ansi256)
+      @depth = depth
+    end
+
+    def render(previous, canvas)
+      out = +""
+      if full_repaint?(previous, canvas)
+        out << Ansi::CLEAR
+        (1..canvas.rows).each { |row| out << row_paint(canvas, row) }
+      else
+        (1..canvas.rows).each { |row| out << row_diff(canvas, previous, row) }
+      end
+
+      out
+    end
+
+    private
+
+    def full_repaint?(previous, canvas)
+      previous.nil? || !previous.same_size?(canvas)
+    end
+
+    # The whole row, positioned at column 1 (used for a full repaint).
+    def row_paint(canvas, row)
+      Ansi.move(row, 1) + canvas.render_row(row, depth: @depth, enabled: true)
+    end
+
+    # Only the changed span of `row`, positioned at its first changed column; ""
+    # when the row is unchanged.
+    def row_diff(canvas, previous, row)
+      span = canvas.changed_span(previous, row)
+      return "" unless span
+
+      Ansi.move(row, span.first) + canvas.render_row(row, from: span.first, to: span.last, depth: @depth, enabled: true)
+    end
+  end
+end

data/lib/tui_tui/cell.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # One terminal cell; a nil char marks the continuation cell of a wide glyph.
+  Cell = Data.define(:char, :style) do
+    def self.blank = BLANK
+    def continuation? = char.nil?
+  end
+
+  Cell::BLANK = Cell.new(char: " ", style: nil)
+end

data/lib/tui_tui/color_depth.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Resolves the color depth the renderer may safely emit.
+  module ColorDepth
+    TRUECOLOR = %w[truecolor 24bit].freeze
+    MODES = %i[none basic16 ansi256 truecolor].freeze
+
+    def self.detect(env = ENV)
+      return :none if disabled?(env)
+      return :truecolor if TRUECOLOR.include?(env["COLORTERM"])
+
+      :ansi256
+    end
+
+    def self.from(name, env = ENV)
+      # Unknown overrides fall back to auto-detection instead of failing startup.
+      case name.to_s.downcase
+      when "none", "no", "off", "0"
+        :none
+      when "16", "basic", "basic16", "ansi16"
+        :basic16
+      when "256", "ansi256"
+        :ansi256
+      when "truecolor", "24bit", "full"
+        :truecolor
+      else
+        detect(env)
+      end
+    end
+
+    def self.disabled?(env)
+      return true if env.key?("NO_COLOR")
+
+      term = env["TERM"]
+      term.nil? || term.empty? || term == "dumb"
+    end
+  end
+end

data/lib/tui_tui/confirm.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+require_relative "style"
+require_relative "modal"
+require_relative "key_code"
+
+module TuiTui
+  # OK / Cancel confirmation modal.
+  class Confirm < Modal
+    GAP = 2
+
+    attr_reader :focus
+
+    def initialize(message, ok: "OK", cancel: "Cancel", default: :cancel, theme: Theme::DEFAULT)
+      @message = DisplayText.new(message)
+      @ok = button_text(ok)
+      @cancel = button_text(cancel)
+      @focus = default
+      @theme = theme
+    end
+
+    def handle(key)
+      case key
+      when :left, :right, "\t", "h", "l"
+        toggle
+      when "\r", " "
+        @focus
+      when "y", "Y"
+        :ok
+      when "n", "N", :escape, KeyCode::CTRL_C
+        :cancel
+      end
+    end
+
+    def handle_mouse(event)
+      return nil unless event.action == :press && @buttons_row == event.row
+
+      return :ok if hit?(event.col, @ok_at, @ok.width)
+      return :cancel if hit?(event.col, @cancel_at, @cancel.width)
+
+      nil
+    end
+
+    def draw(canvas, size)
+      inner = [@message.width, buttons_width].max
+      rect, col = panel(canvas, inner: inner, body_rows: 3)
+      canvas.text(rect.row + 1, col, @message.center(inner), theme.text)
+      draw_buttons(canvas, rect.row + 3, col, inner)
+      canvas
+    end
+
+    private
+
+    def hit?(col, start, width) = col.between?(start, start + width - 1)
+
+    def toggle
+      @focus = @focus == :ok ? :cancel : :ok
+      nil
+    end
+
+    def draw_buttons(canvas, row, col, inner)
+      start = col + [(inner - buttons_width) / 2, 0].max
+      @buttons_row = row
+      @ok_at = start
+      @cancel_at = start + @ok.width + GAP
+      canvas.text(row, @ok_at, @ok, @focus == :ok ? theme.selection : theme.text)
+      canvas.text(row, @cancel_at, @cancel, @focus == :cancel ? theme.selection : theme.text)
+    end
+
+    def buttons_width = @ok.width + GAP + @cancel.width
+    def button_text(label) = DisplayText.new("[ #{label} ]")
+  end
+end

data/lib/tui_tui/display_text.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "width"
+require_relative "text_sanitizer"
+
+module TuiTui
+  # String wrapper for width-aware truncation, centering, and wrapping.
+  class DisplayText
+    def initialize(string)
+      @string = string.is_a?(DisplayText) ? string.to_s : TextSanitizer.sanitize(string.to_s)
+    end
+
+    def to_s = @string
+
+    def width
+      @string.each_grapheme_cluster.sum { |grapheme| Width.cluster(grapheme) }
+    end
+
+    def truncate(max, marker: "...")
+      return self.class.new("") if max <= 0
+      return self if width <= max
+
+      marker = self.class.new(marker)
+      budget = [max - marker.width, 0].max
+      kept = +""
+      used = 0
+      @string.each_grapheme_cluster do |grapheme|
+        grapheme_width = Width.cluster(grapheme)
+        break if used + grapheme_width > budget
+
+        kept << grapheme
+        used += grapheme_width
+      end
+
+      self.class.new(kept + marker.to_s)
+    end
+
+    def center(columns)
+      gap = columns - width
+      return self if gap <= 0
+
+      left = gap / 2
+      self.class.new((" " * left) + @string + (" " * (gap - left)))
+    end
+
+    def wrap(max, indent: "")
+      return [self] if max <= 0 || width <= max
+
+      indent = self.class.new(indent)
+      chunks = []
+      current = +""
+      current_width = 0
+      budget = max
+      @string.each_grapheme_cluster do |grapheme|
+        grapheme_width = Width.cluster(grapheme)
+        if current_width + grapheme_width > budget && !current.empty?
+          chunks << current
+          current = +""
+          current_width = 0
+          budget = [max - indent.width, 1].max
+        end
+
+        current << grapheme
+        current_width += grapheme_width
+      end
+
+      chunks << current unless current.empty?
+      return [self] if chunks.empty?
+
+      [self.class.new(chunks.first)] + chunks[1..].map { |chunk| self.class.new(indent.to_s + chunk) }
+    end
+  end
+end

data/lib/tui_tui/event.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Runtime event values.
+  KeyEvent = Data.define(:key)
+  ResizeEvent = Data.define(:size)
+  TickEvent = Data.define
+  MouseEvent = Data.define(:action, :button, :col, :row)
+  EofEvent = Data.define
+end

data/lib/tui_tui/event_stream.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "event"
+require_relative "key_reader"
+
+module TuiTui
+  # Converts terminal input readiness and resize notifications into runtime events.
+  class EventStream
+    def initialize(input:, size:)
+      @input = input
+      @size = size
+      @key_reader = KeyReader.new
+      @resized = false
+      @queue = []
+    end
+
+    def resized!
+      @resized = true
+    end
+
+    def next_event(tick: 0.1)
+      return @queue.shift unless @queue.empty?
+
+      if @resized
+        @resized = false
+        return ResizeEvent.new(size: @size.size)
+      end
+
+      ready = IO.select([@input], nil, nil, tick)
+      return TickEvent.new unless ready
+
+      raw = @key_reader.read_all(@input)
+      return EofEvent.new if raw.nil?
+
+      @queue.concat(raw.map { |event| event.is_a?(MouseEvent) ? event : KeyEvent.new(key: event) })
+      @queue.shift
+    end
+  end
+end

data/lib/tui_tui/focus_ring.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Immutable focus state for a fixed set of targets.
+  class FocusRing
+    attr_reader :current
+
+    def initialize(*targets, current: nil)
+      @targets = targets.flatten.freeze
+      raise ArgumentError, "FocusRing needs at least one target" if @targets.empty?
+
+      @current = current || @targets.first
+    end
+
+    def focused?(target) = @current == target
+
+    def next
+      focus(@targets[(@targets.index(@current) + 1) % @targets.size])
+    end
+
+    def focus(target)
+      @targets.include?(target) ? self.class.new(@targets, current: target) : self
+    end
+  end
+end

data/lib/tui_tui/fuzzy.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # Query-prepared subsequence matcher used to rank many candidates consistently.
+  class Fuzzy
+    Match = Data.define(:score, :positions)
+
+    BOUNDARY = "/\\_-. ".freeze
+
+    def initialize(query)
+      @query = query.to_s.downcase.grapheme_clusters
+    end
+
+    def match(string)
+      return Match.new(score: 0, positions: []) if @query.empty?
+
+      haystack = string.downcase.grapheme_clusters
+      positions = []
+      from = 0
+      @query.each do |grapheme|
+        at = (from...haystack.size).find { |i| haystack[i] == grapheme } or return nil
+
+        positions << at
+        from = at + 1
+      end
+
+      Match.new(score: score(haystack, positions), positions: positions)
+    end
+
+    def rank(candidates)
+      candidates
+        .filter_map do |item|
+          found = match(block_given? ? yield(item) : item)
+          [item, found] if found
+        end
+        .sort_by { |(_item, found)| -found.score }
+    end
+
+    private
+
+    def score(graphemes, positions)
+      total = 0
+      positions.each_with_index do |pos, i|
+        total += 10
+        total += 6 if i.positive? && positions[i - 1] == pos - 1
+        total += 8 if boundary?(graphemes, pos)
+      end
+
+      total - (positions.last - positions.first)
+    end
+
+    def boundary?(graphemes, pos)
+      pos.zero? || BOUNDARY.include?(graphemes[pos - 1])
+    end
+  end
+end