tui_tui 0.2.0 → 0.4.0

data/lib/tui_tui/test_runtime.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "runtime"
+require_relative "render_context"
+require_relative "events"
+require_relative "size"
+require_relative "box_chrome"
+
+module TuiTui
+  # The Runtime with the Screen removed, for testing apps: inject events, then
+  # assert on the folded model (`app`), the accumulated `commands`, `quit?`,
+  # and the rendered view (`screen` / `canvas`). Events fold exactly as in
+  # Runtime (via Runtime.step — the shared pure part of the loop, including
+  # the inert-tick rule and unknown-command validation). Not loaded by
+  # `require "tui_tui"` — opt in with `require "tui_tui/test_runtime"`.
+  class TestRuntime
+    attr_reader :app, :commands
+
+    def initialize(app, rows: 24, cols: 80)
+      @app = app
+      @size = Size.new(rows: rows, cols: cols)
+      @commands = []
+      @quit = false
+    end
+
+    def quit? = @quit
+
+    def key(k) = fold(KeyEvent.new(key: k))
+
+    # One KeyEvent per grapheme cluster, as typing arrives from a terminal.
+    def type(str)
+      str.each_grapheme_cluster { |grapheme| key(grapheme) }
+      self
+    end
+
+    # Same rule as Runtime: a tick reaches `update` only when the app
+    # implements `wants_tick?` and it returns true; otherwise Runtime.step
+    # treats the tick as inert and nothing is folded.
+    def tick = fold(TickEvent.new)
+
+    def resize(rows:, cols:)
+      @size = Size.new(rows: rows, cols: cols)
+      fold(ResizeEvent.new(size: @size))
+    end
+
+    def mouse(action:, col:, row:, button: nil)
+      fold(MouseEvent.new(action: action, button: button, col: col, row: row))
+    end
+
+    # The current view as Canvas#to_text (a style-free string).
+    def screen = canvas.to_text
+
+    # The current view's Canvas, for cell-level style assertions. Built like
+    # Runtime's: a RenderContext, so legacy `view(size)` apps work too.
+    def canvas = @app.view(RenderContext.new(size: @size, chrome: BoxChrome::ASCII))
+
+    private
+
+    def fold(event)
+      raise "tui_tui: app already quit" if @quit
+
+      folded = Runtime.step(@app, event)
+      return self if folded.nil? # inert tick
+
+      app, commands = folded
+      @commands.concat(commands)
+      app.nil? ? @quit = true : @app = app
+      self
+    end
+  end
+end

data/lib/tui_tui/text_input.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+require_relative "key_code"
+
+module TuiTui
+  # A single-line, grapheme-aware text buffer with a cursor: the editing model
+  # shared by the prompt, search bars, command-palette queries, and editable
+  # cells. It is Canvas-agnostic — it knows only graphemes, cursor position, and
+  # display columns — so the same model drives any chrome around it.
+  #
+  # Editing happens by grapheme cluster, so the cursor never lands inside an
+  # emoji modifier or a base+combining-mark pair, and a combining mark typed
+  # after its base merges into one grapheme.
+  #
+  # The buffer owns only the *editing* keys (text, Backspace/Delete, arrows,
+  # Home/End) via #handle_editing; semantic keys like Enter and Escape belong to
+  # the host, which decides what they mean.
+  class TextInput
+    # The cursor as a grapheme index in 0..length.
+    attr_reader :cursor
+
+    def initialize(value: "")
+      @graphemes = value.grapheme_clusters
+      @cursor = @graphemes.length
+    end
+
+    def value = @graphemes.join
+    def empty? = @graphemes.empty?
+    def length = @graphemes.length
+
+    # Move the cursor, clamping into 0..length.
+    def cursor=(index)
+      @cursor = index.clamp(0, @graphemes.length)
+    end
+
+    # Handle an editing key, returning true if it was consumed. Enter, Escape and
+    # any other non-editing key return false so the host can act on them.
+    def handle_editing(key)
+      case key
+      when KeyCode::BACKSPACE, :backspace then delete_back
+      when :delete then delete_forward
+      when :left then left
+      when :right then right
+      when :home then to_home
+      when :end then to_end
+      when String then return type(key)
+      else return false
+      end
+      true
+    end
+
+    # Insert `key` as literal text when it is printable (no control bytes),
+    # returning whether it was accepted. The entry point for typed input — hosts
+    # that bypass #handle_editing (e.g. append-only queries) call this directly so
+    # the printable rule lives in one place rather than at every call site.
+    def type(key)
+      return false unless printable?(key)
+
+      insert(key)
+      true
+    end
+
+    # Insert a string at the cursor, re-clustering across both boundaries so a
+    # combining mark merges into its neighbour. The cursor lands after the text.
+    def insert(string)
+      head = @graphemes[0...@cursor].join
+      @graphemes = (head + string + @graphemes[@cursor..].join).grapheme_clusters
+      @cursor = (head + string).grapheme_clusters.length
+    end
+
+    def delete_back
+      return false if @cursor.zero?
+
+      @graphemes.delete_at(@cursor - 1)
+      @cursor -= 1
+      true
+    end
+
+    def delete_forward
+      return false if @cursor >= @graphemes.length
+
+      @graphemes.delete_at(@cursor)
+      true
+    end
+
+    def left = (@cursor = [@cursor - 1, 0].max)
+    def right = (@cursor = [@cursor + 1, @graphemes.length].min)
+    def to_home = (@cursor = 0)
+    def to_end = (@cursor = @graphemes.length)
+
+    # The grapheme index whose left edge is closest to `rel` columns past the
+    # grapheme `from` — for mapping a mouse click onto the cursor, where `from`
+    # is the left grapheme of the visible viewport (see #viewport).
+    def index_at(rel, from: 0)
+      return from if rel <= 0
+
+      width = 0
+      @graphemes[from..].each_with_index do |grapheme, i|
+        w = DisplayText.new(grapheme).width
+        return from + i if rel < width + ((w + 1) / 2)
+
+        width += w
+      end
+      @graphemes.length
+    end
+
+    # The visible region of a horizontally-scrolled value: the slice to draw,
+    # scrolled so the cursor (and the cell its block occupies) stays inside `cols`
+    # display columns. Lets a long value be drawn in a narrow field without the
+    # cursor running off the edge.
+    #
+    # `text` is the visible substring, `cursor_col` the display columns from the
+    # viewport's left edge to the cursor (measured from the slice, not the start
+    # of the value), `cursor_grapheme` the grapheme under the cursor (nil at the
+    # end), and `start` the left grapheme index (feed it to #index_at as `from:`).
+    Viewport = Data.define(:text, :cursor_col, :cursor_grapheme, :start)
+
+    def viewport(cols)
+      cols = [cols, 1].max
+      # Reserve room for the block cursor: a real grapheme's width, else one
+      # column for the trailing space drawn when the cursor sits at the end.
+      cell = grapheme_at_cursor ? DisplayText.new(grapheme_at_cursor).width : 1
+      # Scroll right one grapheme at a time until the cursor cell fits, shrinking
+      # the running leading width instead of recomputing it from scratch.
+      start = 0
+      lead = width_before_cursor
+      while start < @cursor && lead + cell > cols
+        lead -= DisplayText.new(@graphemes[start]).width
+        start += 1
+      end
+      Viewport.new(
+        text: visible_slice(start, cols),
+        cursor_col: lead,
+        cursor_grapheme: grapheme_at_cursor,
+        start: start
+      )
+    end
+
+    private
+
+    # Whether `string` is safe to insert as literal text: no C0 control bytes and
+    # no DEL. Multibyte UTF-8 passes, since its bytes are all >= 0x80.
+    def printable?(string) = string.bytes.all? { |byte| byte >= 0x20 && byte != 0x7F }
+
+    # Display columns from the start of the value to the cursor. The viewport-
+    # relative counterpart is Viewport#cursor_col.
+    def width_before_cursor = DisplayText.new(@graphemes[0...@cursor].join).width
+
+    # The grapheme under the cursor (drawn as a block cursor), or nil when the
+    # cursor sits past the last grapheme.
+    def grapheme_at_cursor = @graphemes[@cursor]
+
+    # Graphemes from `start` that fit within `cols` display columns.
+    def visible_slice(start, cols)
+      text = +""
+      width = 0
+      @graphemes[start..].each do |grapheme|
+        w = DisplayText.new(grapheme).width
+        break if width + w > cols
+
+        text << grapheme
+        width += w
+      end
+      text
+    end
+  end
+end

data/lib/tui_tui/text_sanitizer.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module TuiTui
-  # Normalizes text before rendering so malformed input bytes are displayed
-  # safely instead of raising encoding errors.
+  # Encoding hygiene for the render path: replaces malformed byte sequences so a
+  # string can be displayed safely instead of raising encoding errors. (Input
+  # acceptance — rejecting control keys — lives with the input model, TextInput.)
   module TextSanitizer
     module_function
 

data/lib/tui_tui/theme.rb

@@ -31,17 +31,6 @@ module TuiTui
   )
 
   class Theme
-    # Map a symbolic status to its semantic role Style (with common aliases).
-    def status(kind)
-      case kind
-      when :ok, :success then success
-      when :warn, :warning then warning
-      when :error, :danger then danger
-      when :info then info
-      else text
-      end
-    end
-
     # Background-dependent neutral roles.
     SURFACES = {
       dark: {
@@ -116,6 +105,21 @@ module TuiTui
 
     def self.build(background: :dark, hue: :cool) = TABLE.fetch([background, hue])
 
+    LIGHT = Theme.build(background: :light, hue: :cool)
+    WARM = Theme.build(background: :dark, hue: :warm)
+    MONO = Theme.build(background: :dark, hue: :mono)
+    DARK = Theme.build(background: :dark, hue: :cool)
+    DEFAULT = DARK
+
+    PRESETS = {
+      default: DEFAULT,
+      cool: DEFAULT,
+      dark: DARK,
+      light: LIGHT,
+      warm: WARM,
+      mono: MONO
+    }.freeze
+
     # Best-effort terminal background (:light/:dark).
     def self.detect_background(env: ENV)
       case env["TUITUI_BACKGROUND"]&.downcase
@@ -134,22 +138,16 @@ module TuiTui
 
     # Fetch a preset by name (Symbol/String); unknown names fall back to DEFAULT.
     def self.named(name) = PRESETS.fetch(name&.to_sym, DEFAULT)
-  end
-
-  Theme::DARK = Theme.build(background: :dark, hue: :cool)
-  Theme::LIGHT = Theme.build(background: :light, hue: :cool)
-  Theme::DEFAULT = Theme::DARK
-  Theme::WARM = Theme.build(background: :dark, hue: :warm)
-  Theme::MONO = Theme.build(background: :dark, hue: :mono)
 
-  class Theme
-    PRESETS = {
-      default: DEFAULT,
-      cool: DEFAULT,
-      dark: DARK,
-      light: LIGHT,
-      warm: WARM,
-      mono: MONO
-    }.freeze
+      # Map a symbolic status to its semantic role Style (with common aliases).
+    def status(kind)
+      case kind
+      when :ok, :success then success
+      when :warn, :warning then warning
+      when :error, :danger then danger
+      when :info then info
+      else text
+      end
+    end
   end
 end

data/lib/tui_tui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TuiTui
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/tui_tui/widget/list.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../rect"
+require_relative "../line"
+require_relative "scrollbar"
+
+module TuiTui
+  module Widget
+    # 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, auto: false)
+        # With auto:, reserve the gutter only when the content overflows the rect.
+        show_bar = scrollbar && !(auto && @scroll.count <= rect.rows)
+        body, gutter = show_bar ? 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, Line.coerce(yield(index, selected)).truncate(body.cols))
+        end
+
+        draw_scrollbar(canvas, gutter, scrollbar) if gutter
+        canvas
+      end
+
+      # Map a MouseEvent to the list index under it, or nil. Pass the same `rect`
+      # and `scrollbar:` used for `draw` so the gutter column is excluded and the
+      # scroll offset matches what was rendered. Returns nil for clicks outside the
+      # body or below the last item.
+      def index_at(rect, event, scrollbar: nil)
+        body = scrollbar ? rect.split_gutter.first : rect
+        return nil unless body.hit?(event)
+
+        index = @scroll.top + (event.row - body.row)
+        index < @scroll.count ? index : nil
+      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
+    end
+  end
+end

data/lib/tui_tui/widget/progress.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../display_text"
+
+module TuiTui
+  module Widget
+    # A stateless horizontal progress bar for a 1-row rect.
+    # The caller passes the ratio and Theme roles (e.g. bar_style:
+    # theme.selection, track_style: theme.muted); default glyphs are ASCII
+    # (README N7). If the rect is taller than one row, every row gets the bar.
+    module Progress
+      module_function
+
+      def draw(canvas, rect, ratio, bar_style:, track_style: nil, char: "#", track_char: "-")
+        return canvas if rect.rows <= 0 || rect.cols <= 0
+
+        filled = (rect.cols * ratio.to_f.clamp(0.0, 1.0)).round
+        # char / track_char are meant to be 1 column wide (the ASCII defaults
+        # are, per N7); a wider glyph is clipped to the cell budget so the bar
+        # never overflows the rect.
+        bar = DisplayText.new(char * filled).truncate(filled, marker: "").to_s
+        track = DisplayText.new(track_char * (rect.cols - filled)).truncate(rect.cols - filled, marker: "").to_s
+        rect.rows.times do |dr|
+          row = rect.row + dr
+          canvas.text(row, rect.col, bar, bar_style) if filled.positive?
+          canvas.text(row, rect.col + filled, track, track_style) if filled < rect.cols
+        end
+
+        canvas
+      end
+    end
+  end
+end

data/lib/tui_tui/widget/scroll_list.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TuiTui
+  module Widget
+    # 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
+end

data/lib/tui_tui/widget/scrollbar.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../rect"
+require_relative "../style"
+require_relative "../theme"
+
+module TuiTui
+  module Widget
+    # 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: nil, thumb: " ", track_style: TRACK, thumb_style: THUMB)
+        return canvas if rect.rows <= 0
+
+        track ||= canvas.chrome.track
+        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
+end

data/lib/tui_tui/widget/spinner.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TuiTui
+  module Widget
+    # A tiny frame-cycling state machine for "working..." indicators.
+    # It knows nothing about time: the app advances it (typically once per
+    # TickEvent) and draws the current glyph wherever it likes.
+    class Spinner
+      # Default frames are ASCII so every glyph is guaranteed 1 column wide
+      # (README N7). FRAMES_BRAILLE is offered for terminals with good glyph
+      # coverage — whether to use it is the caller's judgement, not ours.
+      FRAMES_ASCII = %w[- \\ | /].freeze
+      FRAMES_BRAILLE = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+      def initialize(frames: FRAMES_ASCII)
+        raise ArgumentError, "spinner needs at least one frame" if frames.empty?
+
+        @frames = frames
+        @index = 0
+      end
+
+      # Step to the next frame (wrapping). Returns self for chaining.
+      def advance
+        @index = (@index + 1) % @frames.length
+        self
+      end
+
+      # The current frame's string.
+      def glyph = @frames[@index]
+
+      def draw(canvas, row, col, style: nil)
+        canvas.text(row, col, glyph, style)
+        canvas
+      end
+    end
+  end
+end

data/lib/tui_tui/widget/status_bar.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../display_text"
+
+module TuiTui
+  module Widget
+    # 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
+end

data/lib/tui_tui/widget/table.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../rect"
+require_relative "../line"
+require_relative "../span"
+require_relative "../display_text"
+require_relative "list"
+
+module TuiTui
+  module Widget
+    # Drawing companion for ScrollList with a fixed header row.
+    # The first row of the rect is the header (built from `columns:`, an array
+    # of [label, width] pairs); the remaining rows are the scrolled body, drawn
+    # by Widget::List. Cell content comes from the caller's block, keeping the
+    # table domain-agnostic: `yield(index, selected)` returns one value per
+    # column — a String (styled with the row's base style) or a Span (its own
+    # style wins, e.g. to accent one cell). Labels may be Spans too.
+    #
+    # Each cell is truncated/padded to its column width (CJK-safe via
+    # DisplayText), columns are joined with a 1-space gap, and anything past
+    # the rect's right edge is clipped.
+    class Table
+      COLUMN_GAP = 1
+
+      def initialize(scroll)
+        @scroll = scroll
+        @list = List.new(scroll)
+      end
+
+      def draw(canvas, rect, columns:, header_style: nil, highlight: nil, scrollbar: nil)
+        header, body = rect.split_rows(1, :rest)
+        draw_header(canvas, header, columns, header_style)
+        return canvas if body.rows <= 0
+
+        @list.draw(canvas, body, highlight: highlight, scrollbar: scrollbar) do |index, selected|
+          format_row(yield(index, selected), columns, selected ? highlight : nil)
+        end
+      end
+
+      # Map a MouseEvent to the row index under it, or nil. The header row and
+      # anything outside the body map to nil. Pass the same `rect` and
+      # `scrollbar:` used for `draw`.
+      def index_at(rect, event, scrollbar: nil)
+        _header, body = rect.split_rows(1, :rest)
+        return nil if body.rows <= 0
+
+        @list.index_at(body, event, scrollbar: scrollbar)
+      end
+
+      private
+
+      def draw_header(canvas, rect, columns, style)
+        return if rect.rows <= 0 || rect.cols <= 0
+
+        canvas.fill(rect, style)
+        line = format_row(columns.map { |label, _width| label }, columns, style)
+        canvas.line(rect.row, rect.col, line.truncate(rect.cols))
+      end
+
+      # One Line for a row: each cell fitted to its column width, joined with
+      # a base-styled gap so a highlight fill is not punched through.
+      def format_row(cells, columns, base_style)
+        spans = []
+        columns.each_with_index do |(_label, width), index|
+          spans << Span[" " * COLUMN_GAP, base_style] unless spans.empty?
+          spans << fit(cells[index], width, base_style)
+        end
+
+        Line.new(spans)
+      end
+
+      # Truncate/pad one cell to `width` columns. A Span keeps its own style;
+      # anything else is rendered with the row's base style.
+      def fit(cell, width, base_style)
+        style = cell.is_a?(Span) ? cell.style : base_style
+        text = DisplayText.new(cell.is_a?(Span) ? cell.text : cell.to_s).truncate(width)
+        Span[text.to_s + (" " * [width - text.width, 0].max), style]
+      end
+    end
+  end
+end