tui_tui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7ad8088986ea6e9bc201be5c89597019f4a256de1531f73184e489233752175
+  data.tar.gz: b08cec47d0355748b9fdf732527f29d2ad2cb104ae1e88c0af5c17a9e488f552
+SHA512:
+  metadata.gz: 4058461db872786a4db951d4b1cd4b789ca7cc5cdfc07eeec8be7c4f2d1290bca30916f2405fe021f870465d74acab0f886128705567aca961346f389a048684
+  data.tar.gz: 3634ec3d3c0da6967adf48af668790559087690e543352a9bb3690d61b435553689e46647cbb13b8619deec409abd19fa95f9bb286d8140baaa1d328237ad114

data/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true # bundle install + cache gems
+      - name: Run the test suite
+        run: bundle exec rake

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Masayoshi Takahashi (@takahashim)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# TuiTui
+
+TuiTui is a small terminal UI toolkit for Ruby, with no external dependencies.
+
+It uses a lightweight, TEA-inspired (MVU) architecture: the app object is the model,
+`update(event)` returns the next app, and `view(size)` renders a `Canvas` that the runtime paints.
+
+## Usage
+
+An app is any object with two methods: `view(size)` returns a `Canvas`, and
+`update(event)` returns the next app (or `:quit`). `Runtime#run` drives the loop.
+
+```ruby
+require "tui_tui"
+
+class Counter
+  def initialize(count = 0) = @count = count
+
+  def view(size)
+    TuiTui::Canvas.blank(size).text(1, 1, "count: #{@count}   (+/- to change, q to quit)")
+  end
+
+  def update(event)
+    return self unless event.is_a?(TuiTui::KeyEvent)
+
+    case event.key
+    when "+", "=" then Counter.new(@count + 1)
+    when "-", "_" then Counter.new(@count - 1)
+    when "q", TuiTui::KeyCode::CTRL_C then :quit
+    else self
+    end
+  end
+end
+
+TuiTui::Runtime.new(Counter.new).run
+```
+
+See [`examples/`](examples) for larger apps.
+Each is runnable with `ruby examples/<name>.rb`.
+
+- `examples/counter.rb` — the smallest possible app
+- `examples/widgets.rb` — built-in modal widgets
+- `examples/file_browser.rb` — two-pane file browser
+- `examples/todo.rb` — todo list with prompts and filtering
+- `examples/csv_viewer.rb` — fixed-header CSV table viewer
+
+## Non-functional requirements
+
+TuiTui is built around a small set of non-functional requirements (NFRs).
+
+#### N1: Minimal dependencies.
+
+Depends only on `io/console`, which is a default gem.
+
+#### N2: Testable without a terminal.
+
+State transitions (`update`) and drawing (`view`) are pure functions.
+Only the driver (`Screen`) touches the terminal.
+
+This makes apps and widgets unit-testable and snapshot-testable in headless environments.
+
+#### N3: Terminal safety.
+
+Raw mode, the alternate screen, and cursor visibility are always restored.
+This applies to normal exits, exceptions, and signals.
+
+This prevents the terminal from being left in a broken state.
+The `Screen.run` block form guarantees this behavior through `TerminalSession`.
+
+#### N4: No flicker.
+
+Only the frame diff is written.
+Each frame is flushed with a single `write`.
+
+#### N5: Full-width aware.
+
+Columns never misalign.
+Display width is measured using a small built-in table based on East Asian Width.
+
+Glyphs are clipped at region edges, not split across them.
+
+#### N6: Performance.
+
+Movement and redraw stay responsive, even with large content.
+Only changed rows are repainted, so cost scales with the change, not the screen size.
+
+#### N7: Width-safe UI chrome (ASCII).
+
+Self-drawn chrome uses only ASCII, color, and spacing.
+ASCII characters have a guaranteed width of 1.
+
+Unicode box-drawing characters are never used.
+Their width can vary under CJK terminal settings and break layouts.
+
+Vertical splits are drawn as a colored one-column gutter.
+Rules are drawn with ASCII `-` or a background fill.
+Selection is drawn with `:reverse`.
+
+Content text, such as Japanese data, is measured with `Width`.
+It is clipped or padded to fit the available space.
+
+## Configuration
+
+Environment variables (all optional):
+
+- `TUITUI_MOUSE` — set to `0`/`off`/`false` to disable mouse reporting (on by default).
+- `TUITUI_BACKGROUND` — `light` or `dark` to pick the theme for your terminal background. Without it, `COLORFGBG` is read if present, otherwise `dark` is assumed (reliable auto-detection isn't possible on all terminals).
+
+## Installation
+
+```bash
+bundle add tui_tui
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install tui_tui
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/takahashim/tui_tui.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/clock.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Shows the tick seam: a big, resizable, always-animating clock. The app opts in
+# to timer ticks with `wants_tick?`; the Runtime delivers a TickEvent on its poll
+# interval and re-renders, so it animates without input. The time is drawn as
+# large digits — each font pixel is an N-cell block of background color, so the
+# banner is ASCII-only (N7), no block-drawing glyphs. The size auto-fits the
+# terminal and is adjustable with +/-.
+#
+#   ruby examples/clock.rb
+#
+# Keys: + / - bigger / smaller, q (or Ctrl-C) quit.
+
+require_relative "../lib/tui_tui"
+
+module ClockSample
+  TIME = TuiTui::Style.new(bg: :cyan) # a lit "pixel" of the big digits
+  HINT = TuiTui::Style.new(attrs: [:dim])
+  SPINNER = %w[| / - \\].freeze
+
+  GLYPH_W = 3 # font cells wide
+  GLYPH_H = 5 # font cells tall
+
+  # 3x5 ASCII fonts; "#" is a lit pixel, " " is blank.
+  FONT = {
+    "0" => ["###", "# #", "# #", "# #", "###"],
+    "1" => ["  #", "  #", "  #", "  #", "  #"],
+    "2" => ["###", "  #", "###", "#  ", "###"],
+    "3" => ["###", "  #", "###", "  #", "###"],
+    "4" => ["# #", "# #", "###", "  #", "  #"],
+    "5" => ["###", "#  ", "###", "  #", "###"],
+    "6" => ["###", "#  ", "###", "# #", "###"],
+    "7" => ["###", "  #", "  #", "  #", "  #"],
+    "8" => ["###", "# #", "###", "# #", "###"],
+    "9" => ["###", "# #", "###", "  #", "###"],
+    ":" => ["   ", " # ", "   ", " # ", "   "],
+  }.freeze
+
+  class Clock
+    def initialize
+      @ticks = 0
+      @scale = nil # set to the auto-fit size on first view; adjusted with +/-
+    end
+
+    def wants_tick? = true
+
+    def update(event)
+      case event
+      when TuiTui::KeyEvent then handle_key(event.key)
+      when TuiTui::TickEvent then (@ticks += 1) && self
+      else self
+      end
+    end
+
+    def view(size)
+      canvas = TuiTui::Canvas.blank(size)
+      time = Time.now.strftime("%H:%M:%S")
+      @scale = (@scale || max_scale(size, time)).clamp(1, max_scale(size, time))
+      box = TuiTui::Rect.centered(size, cols: banner_width(time, @scale), rows: banner_height(@scale))
+      draw_big(canvas, box.row, box.col, time, @scale)
+      canvas.text(size.rows, 1, " #{SPINNER[@ticks % SPINNER.length]}  +/- size  q quit", HINT)
+      canvas
+    end
+
+    private
+
+    def handle_key(key)
+      case key
+      when "q", TuiTui::KeyCode::CTRL_C then return :quit
+      when "+", "=" then @scale += 1 # clamped to fit in view
+      when "-", "_" then @scale -= 1
+      end
+      self
+    end
+
+    # A font pixel is `2*scale` columns by `scale` rows (≈ square on screen, since
+    # terminal cells are about twice as tall as wide); glyphs sit `2*scale` apart.
+    def banner_width(text, scale) = (text.length * GLYPH_W + (text.length - 1)) * 2 * scale
+    def banner_height(scale) = GLYPH_H * scale
+
+    # The largest scale whose banner still fits the terminal (at least 1).
+    def max_scale(size, text)
+      by_width = size.cols / banner_width(text, 1)
+      by_height = (size.rows - 1) / GLYPH_H
+      [[by_width, by_height].min, 1].max
+    end
+
+    def draw_big(canvas, top, left, text, scale)
+      pixel_w = 2 * scale
+      col = left
+      text.each_char do |ch|
+        glyph = FONT[ch]
+        next unless glyph
+
+        glyph.each_with_index do |line, r|
+          line.each_char.with_index do |pixel, c|
+            next unless pixel == "#"
+
+            cell = TuiTui::Rect.new(row: top + (r * scale), col: col + (c * pixel_w), rows: scale, cols: pixel_w)
+            canvas.fill(cell, TIME)
+          end
+        end
+        col += (GLYPH_W * pixel_w) + (2 * scale)
+      end
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  TuiTui::Runtime.new(ClockSample::Clock.new).run(tick: 0.1)
+end

data/examples/counter.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The smallest possible TuiTui app: a counter. It shows the whole contract and
+# nothing else — `view(size) -> Canvas` and `update(event) -> self | :quit` —
+# with no widgets and no layout.
+#
+#   ruby examples/counter.rb
+#
+# Keys: j / + / ↑ increment, k / - / ↓ decrement, r reset, q (or Ctrl-C) quit.
+
+require_relative "../lib/tui_tui"
+
+module CounterSample
+  BIG = TuiTui::Style.new(fg: :green, attrs: [:bold])
+  HINT = TuiTui::Style.new(attrs: [:dim])
+
+  class Counter
+    def initialize
+      @count = 0
+    end
+
+    def update(event)
+      return self unless event.is_a?(TuiTui::KeyEvent)
+
+      case event.key
+      when "q", TuiTui::KeyCode::CTRL_C then return :quit
+      when "j", "+", :up then @count += 1
+      when "k", "-", :down then @count -= 1
+      when "r" then @count = 0
+      end
+      self
+    end
+
+    def view(size)
+      canvas = TuiTui::Canvas.blank(size)
+      label = "count: #{@count}"
+      box = TuiTui::Rect.centered(size, cols: TuiTui::DisplayText.new(label).width, rows: 1)
+      canvas.text(box.row, box.col, label, BIG)
+      canvas.text(size.rows, 1, " j/+ up   k/- down   r reset   q quit", HINT)
+      canvas
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  TuiTui::Runtime.new(CounterSample::Counter.new).run
+end

data/examples/csv_viewer.rb

@@ -0,0 +1,233 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# A small CSV viewer. It demonstrates a table-shaped app with a fixed header,
+# vertical row selection, horizontal column navigation, width-aware cell
+# clipping, and a status bar. Pass a CSV path, or run it without arguments to
+# browse the built-in sample data.
+#
+#   ruby examples/csv_viewer.rb [CSV]
+#
+# Keys: j/k (or ↑/↓) move rows, h/l (or ←/→) move columns, Space page down,
+# b page up, g/G top/bottom, 0/$ first/last column, q (or Ctrl-C) quit.
+
+require "csv"
+require_relative "../lib/tui_tui"
+
+module CsvViewerSample
+  SAMPLE = <<~CSV
+    id,name,role,country,notes
+    1,Ada Lovelace,Mathematician,United Kingdom,First programmer
+    2,Grace Hopper,Computer Scientist,United States,Popularized machine-independent languages
+    3,高橋,Engineer,日本,日本語のセルも幅安全に表示
+    4,Margaret Hamilton,Software Engineer,United States,Apollo guidance software
+    5,Katherine Johnson,Mathematician,United States,Orbital mechanics calculations
+    6,Edsger Dijkstra,Computer Scientist,Netherlands,Shortest paths and structured programming
+  CSV
+
+  S = TuiTui::Style
+  STYLE = {
+    title: S.new(attrs: [:bold]),
+    dim: S.new(attrs: [:dim]),
+    header: S.new(fg: :bright_white, bg: 238, attrs: [:bold]),
+    row_number: S.new(fg: :bright_black),
+    selected_row: S.new(bg: 236),
+    selected_cell: S.new(attrs: [:reverse, :bold]),
+    status: S.new(attrs: [:reverse]),
+    error: S.new(fg: :bright_red, attrs: [:bold]),
+    accent: S.new(fg: :cyan, attrs: [:bold]),
+  }.freeze
+
+  ROW_NUMBER_WIDTH = 6
+  MIN_COLUMN_WIDTH = 6
+  MAX_COLUMN_WIDTH = 28
+
+  class CsvViewer
+    def initialize(path)
+      @path = path
+      @header, @rows, @error = load_csv(path)
+      @list = TuiTui::ScrollList.new(@rows.size)
+      @col = 0
+      @left_col = 0
+      @page = 1
+      @widths = column_widths
+    end
+
+    def update(event)
+      return self unless event.is_a?(TuiTui::KeyEvent)
+
+      case event.key
+      when "q", TuiTui::KeyCode::CTRL_C then return :quit
+      when "j", :down then @list.move(1)
+      when "k", :up then @list.move(-1)
+      when " ", :pgdn then @list.move(@page)
+      when "b", :pgup then @list.move(-@page)
+      when "g", :home then @list.to_top
+      when "G", :end then @list.to_end
+      when "h", :left then move_col(-1)
+      when "l", :right then move_col(1)
+      when "0" then @col = 0
+      when "$" then @col = last_col
+      end
+      self
+    end
+
+    def view(size)
+      canvas = TuiTui::Canvas.blank(size)
+      body, footer = split_footer(size)
+      detail, status = footer.split_h(1)
+      table = body
+
+      @page = [table.rows - 1, 1].max
+      @list.ensure_visible(@page)
+      ensure_column_visible(table.cols - ROW_NUMBER_WIDTH)
+
+      draw_table(canvas, table)
+      draw_detail(canvas, detail)
+      draw_status(canvas, status)
+      canvas
+    end
+
+    private
+
+    def load_csv(path)
+      if path
+        rows = CSV.read(path, headers: false)
+        source = File.expand_path(path)
+      else
+        rows = CSV.parse(SAMPLE, headers: false)
+        source = "(sample data)"
+      end
+
+      header = normalize_row(rows.shift || [])
+      data = rows.map { |row| normalize_row(row) }
+      width = [header.size, data.map(&:size).max || 0].max
+      header = default_header(width) if header.empty?
+      header = pad_row(header, width)
+      data = data.map { |row| pad_row(row, width) }
+      [header, data, nil]
+    rescue CSV::MalformedCSVError, SystemCallError => e
+      [["error"], [["#{e.class}: #{e.message}"]], "#{source || path}: #{e.message}"]
+    end
+
+    def normalize_row(row) = row.map { |cell| cell.to_s }
+    def pad_row(row, width) = row + Array.new(width - row.size, "")
+    def default_header(width) = Array.new(width) { |i| "column_#{i + 1}" }
+
+    def split_footer(size)
+      whole = TuiTui::Rect.new(row: 1, col: 1, rows: size.rows, cols: size.cols)
+      return [whole, TuiTui::Rect.new(row: size.rows, col: 1, rows: 0, cols: size.cols)] if size.rows < 3
+
+      whole.split_h(size.rows - 2)
+    end
+
+    def draw_table(canvas, rect)
+      return if rect.rows <= 0 || rect.cols <= 0
+
+      canvas.fill(TuiTui::Rect.new(row: rect.row, col: rect.col, rows: 1, cols: rect.cols), STYLE[:header])
+      canvas.text(rect.row, rect.col, fit("#", ROW_NUMBER_WIDTH), STYLE[:header])
+      each_visible_column(rect.cols - ROW_NUMBER_WIDTH) do |index, col, width|
+        style = index == @col ? STYLE[:selected_cell] : STYLE[:header]
+        canvas.text(rect.row, col, fit(@header[index], width), style)
+      end
+
+      if @rows.empty?
+        canvas.text(rect.row + 1, rect.col + 1, "No rows", STYLE[:dim]) if rect.rows > 1
+        return
+      end
+
+      @list.each_visible([rect.rows - 1, 0].max) do |row_index, offset|
+        row = rect.row + 1 + offset
+        selected = row_index == @list.cursor
+        canvas.fill(TuiTui::Rect.new(row: row, col: rect.col, rows: 1, cols: rect.cols), STYLE[:selected_row]) if selected
+        canvas.text(row, rect.col, fit((row_index + 1).to_s, ROW_NUMBER_WIDTH), selected ? STYLE[:selected_row] : STYLE[:row_number])
+        each_visible_column(rect.cols - ROW_NUMBER_WIDTH) do |index, col, width|
+          style = selected && index == @col ? STYLE[:selected_cell] : (selected ? STYLE[:selected_row] : nil)
+          canvas.text(row, col, fit(@rows[row_index][index], width), style)
+        end
+      end
+    end
+
+    def draw_detail(canvas, rect)
+      return if rect.rows <= 0
+
+      canvas.hline(rect.row, rect.col, rect.cols, "-", STYLE[:dim])
+      return if @rows.empty?
+
+      label = @header[@col] || "column_#{@col + 1}"
+      value = @rows[@list.cursor][@col].to_s
+      text = "#{label}: #{value}"
+      canvas.text(rect.row, rect.col + 1, TuiTui::DisplayText.new(text).truncate(rect.cols - 1), STYLE[:accent])
+    end
+
+    def draw_status(canvas, rect)
+      return if rect.rows <= 0
+
+      canvas.fill(rect, STYLE[:status])
+      left = @error || " #{@path ? File.basename(@path) : "sample.csv"}"
+      canvas.text(rect.row, rect.col, TuiTui::DisplayText.new(left).truncate(rect.cols), @error ? STYLE[:error] : STYLE[:status])
+
+      right = " row #{@list.cursor + 1}/#{[@rows.size, 1].max}  col #{@col + 1}/#{@header.size}  j/k rows  h/l cols  q quit "
+      width = TuiTui::DisplayText.new(right).width
+      return if width >= rect.cols
+
+      canvas.text(rect.row, rect.col + rect.cols - width, right, STYLE[:status])
+    end
+
+    def each_visible_column(available)
+      return if available <= 0
+
+      col = ROW_NUMBER_WIDTH + 1
+      @left_col.upto(last_col) do |index|
+        width = @widths[index]
+        break if col + width - 1 > available + ROW_NUMBER_WIDTH
+
+        yield index, col, width
+        col += width
+      end
+    end
+
+    def ensure_column_visible(available)
+      return if available <= 0
+
+      @left_col = @col if @col < @left_col
+      while @col >= first_hidden_column(available)
+        @left_col += 1
+      end
+      @left_col = @left_col.clamp(0, last_col)
+    end
+
+    def first_hidden_column(available)
+      used = 0
+      @left_col.upto(last_col) do |index|
+        used += @widths[index]
+        return index if used > available
+      end
+      last_col + 1
+    end
+
+    def move_col(delta)
+      @col = (@col + delta).clamp(0, last_col)
+    end
+
+    def last_col = [@header.size - 1, 0].max
+
+    def column_widths
+      @header.each_index.map do |index|
+        values = [@header[index], *@rows.first(200).map { |row| row[index] }]
+        width = values.map { |value| TuiTui::DisplayText.new(value.to_s).width }.max || MIN_COLUMN_WIDTH
+        (width + 2).clamp(MIN_COLUMN_WIDTH, MAX_COLUMN_WIDTH)
+      end
+    end
+
+    def fit(value, width)
+      text = TuiTui::DisplayText.new(" #{value}")
+      text = text.truncate(width - 1) if text.width >= width
+      text.to_s + (" " * [width - text.width, 0].max)
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  TuiTui::Runtime.new(CsvViewerSample::CsvViewer.new(ARGV[0])).run
+end