text-ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 412150d9f77ef6b3363eaae39bcc64a4ddc73a5a9ed3fa76a54841eca070549a
+  data.tar.gz: 9ae1904192edd13412b87667a9b0bf62c1ee601facc498feba703f5e85750d9a
+SHA512:
+  metadata.gz: 05ded2430b82482f2e7d3d4074159a9bec9684304bc4db69913ff3f9d0562664641d31c593a22b661c5cb30c9b91111c53c41c9bd93578c921cb00c036a15b1d
+  data.tar.gz: d46560ec1bdd4cfaa563b6f9b978b3276565f721d451ae5fce5ac302805ac028708fb2f6486e4d551b52ca4ff9b4e7e241a9e635bdaf34f8069a42c3e76e2af6

data/README.md

@@ -0,0 +1,33 @@
+# Description
+
+A gem to build Text User Interface of nested boxes for console with custom dynamic content.
+
+It allows to positions and align nested boxes through notions of rows and columns to structure data.
+
+## Usage
+
+The gem expects you to have the main application that does its job separately.
+
+In a meanwhile, TUI's thread would re-draw layout with you custom content on console.
+
+See [example](./bin/example.rb) for some usage.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `ruby -Ilib:test test/test_tui.rb` to run the tests.
+
+## Contributing
+
+Feel free to submit bug reports and merge requests.
+
+# Docs
+
+`yard doc` generates some documentation.
+
+`yard server --reload` starts a server with documentation available at http://localhost:8808
+
+# TODOs
+
+- resurrect logging
+- handle Ctrl+C
+- provide interface to control data fetching: frequency, caching, make it parallel

data/lib/tui/assets.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Static assets to draw boxes.
+# Are used mainly in {Format#box!}
+module Tui::Assets
+  CORNERS = {
+    sharp: '┏┓┗┛',
+    round: '╭╮╰╯'
+  }.freeze
+  LINES = {
+    single: '│─'
+  }.freeze
+end

data/lib/tui/block.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative 'format'
+
+module Tui
+  # Basic TUI building block.
+  #
+  # In a nutshell, all blocks are columns ({Block#column}) with {::String}s in it printed vertically one by one (see {#to_s}).
+  # So a row is a way to compose multiple columns to a single "column" (see {Block#row}), which is an {::Array} of lines anyway.
+  class Block
+
+    attr_reader :width
+    attr_reader :array
+
+    # Mix-in formatting methods.
+    # The {Blocks} class has only methods to make nested blocks
+    include Format
+
+    # Make a column with several rows in it. Rows could be other {Block}s or just {::String}s.
+    #
+    # The method actually transform array or "rows" to a single column right away.
+    # @example
+    #   Block.column "some", "other"                   # "some" and "other will be centered in the column by default
+    #   Block.column "some", "other", align: :left     # "some" and "other" will be aligned to the left
+    #   Block.column
+    #     Block.row("one", "two"),
+    #     "three"
+    #   ]}                                             # "one" and "two" will be printed in the first row, "three" will be below them centered
+    #   Block.column("some", "other") { |el| el.box! } # box both string then place boxes to a column
+    #
+    # @param rows array of rows ({Block}s / {::String}s)
+    # @param align how to align blocks between each other: :center (default), :right, :left
+    # @param block individual row processor, the block is supplied with {Block}s
+    def self.column *rows, align: :center, &block
+      # row could be a String, make an array of horizontal lines from it
+      rows.collect! { |col| col.is_a?(Block) ? col : Block.new(col) }
+      rows.collect!(&block) if block_given? # pre-process "rows"
+      max_row_width = rows.collect(&:width).max
+      Block.new rows.collect! { |blk|
+        extra_columns = max_row_width - blk.width
+        case align
+        when :left then blk.collect! { |line| line + ' ' * extra_columns }
+        when :right then blk.collect! { |line| ' ' * extra_columns + line }
+        else
+          blk.h_pad!(extra_columns / 2)
+          extra_columns.odd? ? blk.collect! { |line| line + ' ' } : blk
+        end
+        blk.array # get the array to join using builtin flatten
+      }.flatten!
+    end
+
+    # Compose a row of other {Block}s or {::String}s.
+    #
+    # The method actually squashes a row of columns (blocks) to a single block (column)
+    # @example
+    #   Block.row "some", "other"                         # => "someother"
+    #   Block.row "some", ["other", "foo"], aligh: bottom # "some" will be shifted down by 1 line
+    #   Block.row("some", "other") { |blk| blk.box! }     # both columns will be enclosed in a box
+    #
+    # @param cols array of columns ({Block}s / {::String}s) to squash
+    # @param align how to align blocks in the row: :center, :top, :bottom
+    # @param block individual column processor
+    def self.row *cols, align: :center, &block
+      cols.collect! { |col| col.is_a?(Block) ? col : Block.new(col) }
+      cols.collect!(&block) if block_given? # pre-process columns
+      max_col_height = cols.collect(&:height).max
+      Block.new cols.collect! { |col|
+        extra_lines = max_col_height - col.height
+        case align
+        when :top then col << Array.new(extra_lines, '')
+        when :bottom then col >> Array.new(extra_lines, '')
+        else
+          col.v_pad!(extra_lines / 2)
+          col << '' if extra_lines.odd?
+        end
+        col.v_align! # is needed due to transpose call below
+        col.array # get the array to process using builtin methods
+      }.transpose.collect(&:join)
+    end
+
+    # "Render" the Block to print to the console.
+    # As each block and operation just transforms a list of Strings,
+    # the whole "rendering" is as simple as ...
+    def to_s
+      @array.join "\n"
+    end
+
+    # Add extra lines from the supplied array to the block;
+    # no auto-alignment is performed, see {#v_align!} to make width even
+    # @param other either {::Array} or {::String} to push back
+    def << other
+      other.is_a?(Array) ? @array += other : @array << other
+      @width = @array.collect(&:size).max
+      self
+    end
+
+    # Add extra lines to the "start" of the block
+    # @param other either {::Array} or {::String} to push_forward
+    # @example
+    #   Block.column '1'
+    #   block << %w[2 3] # now block has %w[2 3 1]
+    def >> other
+      case other
+      when Array
+        @width = [@width, other.collect(&:size).max].max
+        other.reverse_each { |i|
+          @array.unshift i
+        }
+      when String
+        @width = [@width, other.size].max
+        @array.unshift other
+      end
+      self
+    end
+
+    # Get {Block}'s height in symbols
+    # Block is a column => column's height is {Block}'s array size
+    def height
+      @array.size
+    end
+
+    # Modify each "row" of the {Block} inline
+    def collect! &block
+      @array.collect!(&block)
+      @width = @array.collect(&:size).max
+    end
+
+    private
+
+    # Constructor is private.
+    #
+    # {#column} and {#row} are to make blocks;
+    def initialize arg
+      @array = case arg
+               when Array then arg
+               when String then [arg]
+               else [arg.to_s]
+               end
+      @width = @array.collect(&:size).max
+    end
+  end
+end

data/lib/tui/format.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Tui
+  # Collection of low-level {Block} formatting methods.
+  #
+  # Most methods
+  # - mutate the object they are called for => no need to re-assign
+  # - `return self` => are intended to be chained (`block.box!.v_pad!(2)`)
+  #
+  # The module is not to be used directly
+  # and exists just to de-couple formatting methods from the rest.
+  module Format
+
+    # Add horizontal (to the sides) padding to the block.
+    # @param size number of spaces to add
+    def h_pad! size = 1
+      collect! { |line|
+        "#{' ' * size}#{line}#{' ' * size}"
+      }
+      @width += size * 2
+      self
+    end
+
+    # Add vertical padding (before-after) to the block
+    # @param size number of spaces to add
+    def v_pad! size = 1
+      filler = ' ' * @width
+      size.times {
+        self >> filler
+        self << filler
+      }
+      self
+    end
+
+    # Adds spaces around the block
+    # @param size number of spaces to add
+    def pad! size = 1
+      # order matters!
+      v_pad! size
+      h_pad! size
+    end
+
+    # Aligns block elements vertically (by width) by adding spaces.
+    #
+    # Lines (rows) within the block can be of uneven width.
+    # This method changes all lines to have the same # of chars
+    # @param type {Symbol} :left, :center, :right
+    # @param width {Integer} target block width, is ignored if less than @width (look at {fit!})
+    def v_align! type = :left, width: @width
+      line_transformer = case type
+                         when :center
+                           ->(line, num_spaces) { ' ' * (num_spaces / 2) + line.to_s + (' ' * (num_spaces / 2)) + (num_spaces.odd? ? ' ' : '') }
+                         when :right
+                           ->(line, num_spaces) { (' ' * num_spaces) + line.to_s }
+                         else # :left
+                           ->(line, num_spaces) { line.to_s + (' ' * num_spaces) }
+                         end
+
+      return self if width.nil? || @width > width # == case makes all lines width even
+
+      @width = width
+      @array.collect! { |line| line_transformer.call line, @width - line.size }
+      self
+    end
+
+    # Aligns block elements horisontally (by height) by adding spaces.
+    #
+    # New lines get added to the block to have the specified # of lines in total.
+    # @param type {Symbol} :top, :center, :bottom
+    # @param height {Integer} target block height, is ignored if less than @width (look at {fit!})
+    def h_align! type = :top, height: @height
+      return self if height.nil? or @array.size > height
+
+      extra_lines_count = height - @array.size
+      case type
+      when :center
+        (extra_lines_count/2).times { @array.prepend ' ' * @width }
+        (extra_lines_count/2 + (extra_lines_count.odd? ? 1 : 0)).times { @array.append ' ' * @width }
+      when :top
+        (extra_lines_count).times { @array.append ' ' * @width }
+      else # :bottom
+        (extra_lines_count).times { @array.prepend ' ' * @width }
+      end
+
+      self
+    end
+
+    # Align content to the center of the specified width and height.
+    #
+    # @param height {Number} target height
+    # @param width {Number} target width
+    def align! height: nil, width: nil
+      v_align! :center, width: width
+      h_align! :center, height: height
+    end
+
+    # Add a square box around the block.
+    #
+    # It auto-aligns the block, so use {v_align!} beforehand!
+    # if you want custom alignment for the block
+    def box! corners: :round
+      corners = Assets::CORNERS[corners]
+      lines = Assets::LINES[:single]
+      v_align!
+      @array.collect! { |line| "#{lines[0]}#{line}#{lines[0]}" }
+      @array.unshift "#{corners[0]}#{lines[1] * width}#{corners[1]}"
+      @array << "#{corners[2]}#{lines[1] * width}#{corners[3]}"
+      @width += 2
+      self
+    end
+
+    # Fit the current block to a rectangle by
+    # cropping the block and adding a special markers to its content.
+    #
+    # Actual content width and height will be 1 char less to store cropping symbols too.
+    #
+    # Filling does not align content, {v_align!} does.
+    #
+    # @param width width to fit, nil => don't touch width
+    # @param height height to fit, nil =>  don't touch height
+    # @param fill whether to fill {Block} to be of the size of the box
+    def fit! width: nil, height: nil, fill: false
+      # pre-calc width to use below
+      @width = width unless width.nil? || (@width < width && !fill)
+
+      unless height.nil?
+        if @array.size > height
+          @array.slice!((height - 1)..)
+          @array << ('░' * @width)
+        elsif fill && @array.size < height
+          @array += Array.new(height - @array.size, ' ' * @width)
+        end
+      end
+      unless width.nil?
+        collect! { |line|
+          if line.size > width
+            "#{line[...(width - 1)]}░"
+          elsif fill && line.size < width
+            extra = (width - line.size)
+            "#{' ' * (extra/2)}#{line}#{' ' * (extra/2 + (extra.odd? ? 1 : 0))}"
+          else
+            line
+          end
+        }
+      end
+      self
+    end
+
+  end
+end

data/lib/tui/layout.rb

@@ -0,0 +1,21 @@
+require_relative 'block'
+
+# Main window layout.
+#
+# It represents the main window of the application's TUI
+class Tui::Layout
+  # Internal content is expected to be rendered each time => should be callable
+  # @example
+  #   Tui::Layout.new { Block.column "foo", "bar" }
+  def initialize &block
+    @root = block || -> { Tui::Block::column "Hello TUI!" }
+  end
+
+  # Render content to produce a frame, which could be print -ed.
+  def render
+    box = @root.call
+    raise "main window is not a block but #{box.class}" unless box.is_a? Tui::Block
+
+    box
+  end
+end

data/lib/tui/settings.rb

@@ -0,0 +1,13 @@
+# Settings for the TUI.
+#
+# - target_fps - how frequently you want the content to refresh. It's useful to control CPU, console I/O and data fetching usage
+# - window_size - size of the main window, e.g. `{ height: 70, width: 200 }`
+# - draw_main_window - whether to fit content in a box and center it by default within window
+Tui::Settings = Data.define(:target_fps, :window_size, :draw_main_window) do
+  def initialize(
+    target_fps: 30,
+    window_size: { height: 70, width: 200 }.freeze,
+    draw_main_window:  true)
+      super(target_fps:, window_size:, draw_main_window:)
+  end
+end

data/lib/tui.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Tui; end
+
+require 'date'
+require 'io/console'
+
+
+require_relative 'tui/assets'
+require_relative 'tui/block'
+require_relative 'tui/format'
+require_relative 'tui/layout'
+require_relative 'tui/settings'
+
+##
+# Root module / singleton. See {Tui#run} - the main entrypoint.
+module Tui
+  # Delay correction step to maintain FPS
+  DELAY_STEP_MS = 100
+
+  # Frames counter to calculate average FPS
+  @frames_count = 0
+
+  class << self
+
+    # Current delay between redraws
+    attr_reader :delay_ms
+    # Average redraws count / sec
+    attr_reader :current_avg_fps
+
+    ##
+    # The main entrypoint of the TUI
+    # @param layout {Tui::Layout} - UI's layout to render and draw
+    # @param settings {Tui::Settings} - UI's settings that affects UI's behavior
+    # @return {Thread}
+    def run layout, settings = Settings::new
+      raise "expected Layout, found #{layout.class}" unless layout.is_a? Layout
+
+      @settings = settings
+      @started_at = DateTime.now.strftime('%Q').to_i
+      @delay_ms = 1000 / @settings.target_fps
+
+      @thread = Thread.new {
+        loop {
+          clear
+          refresh
+          print @settings.draw_main_window ?
+            layout.render
+                .align!(**effective_window_size)
+                .fit!(**effective_window_size, fill: true)
+                .box!
+            : layout.render
+
+          sleep @delay_ms / 1000.0
+        }
+      }
+
+      @thread
+    end
+
+    private
+
+    def clear
+      print "\e[2J\e[f"
+    end
+
+    # Refresh terminal size and adjust delay
+    def refresh
+      ms_spent = 1 + DateTime.now.strftime('%Q').to_i - @started_at
+
+      @current_avg_fps = @frames_count * 1000.0 / ms_spent
+
+      # TODO: use progression
+      if @settings.target_fps > @current_avg_fps && @delay_ms > DELAY_STEP_MS
+        @delay_ms -= DELAY_STEP_MS
+      end
+
+      if @settings.target_fps < @current_avg_fps && @delay_ms < 1000
+        @delay_ms += DELAY_STEP_MS
+      end
+
+      @frames_count += 1;
+    end
+
+    # Calculate actual content size from settings and available terminal's shape
+    def effective_window_size
+      {
+        height: (IO.console&.winsize&.first.nil? || @settings.window_size[:height] < IO.console.winsize.first ? @settings.window_size[:height] : IO.console.winsize.first) - 4,
+        width: (IO.console&.winsize&.last.nil? || @settings.window_size[:width] < IO.console.winsize.last ? @settings.window_size[:width] : IO.console.winsize.last) - 2
+      }
+    end
+
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: text-ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Skorobogaty Dmitry
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-31 00:00:00.000000000 Z
+dependencies: []
+description: |2
+
+
+  A gem to build Text User Interface of nested boxes for console with custom dynamic content.
+
+  It allows to positions and align nested boxes through notions of rows and columns to structure data.
+email:
+- skorobogaty.dmitry@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/tui.rb
+- lib/tui/assets.rb
+- lib/tui/block.rb
+- lib/tui/format.rb
+- lib/tui/layout.rb
+- lib/tui/settings.rb
+homepage: https://github.com/skorobogatydmitry/tui
+licenses:
+- LGPL-3.0-only
+metadata:
+  homepage_uri: https://github.com/skorobogatydmitry/tui
+  source_code_uri: https://github.com/skorobogatydmitry/tui
+  allowed_push_host: https://rubygems.org/
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Draw nested boxes in console.
+test_files: []