rubytui 1.2.3

data/lib/rubytui/input/parser.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Input
+    # Decodes raw terminal input into {KeyEvent} and {MouseEvent} objects.
+    #
+    # Recognised input: printable ASCII, Enter, Tab, Backspace, Ctrl+letter,
+    # multi-byte UTF-8 characters given as raw bytes (as read by {Reader}), ESC,
+    # Alt+character (ESC followed by one character),
+    # CSI and SS3 key sequences (arrows, Home/End, Insert/Delete, Page Up/Down,
+    # Back-tab, F1-F12, xterm modified arrows such as <tt>ESC [ 1 ; 5 A</tt>),
+    # and SGR and legacy mouse reports.
+    #
+    # @example
+    #   Input::Parser.new.parse("\e[A")  # => KeyEvent(up)
+    class Parser
+      # Parse raw bytes into an Event.
+      #
+      # @param bytes [String, nil] raw bytes of one key press or mouse report
+      # @return [KeyEvent, MouseEvent, nil] the decoded event, or nil if +bytes+
+      #   is nil, empty or not a recognised sequence
+      def parse(bytes)
+        return nil if bytes.nil? || bytes.empty?
+
+        # ESC sequence
+        if bytes.start_with?("\e")
+          parse_escape(bytes)
+        elsif bytes.length == 1
+          parse_single(bytes)
+        else
+          # Multi-byte UTF-8 character
+          KeyEvent.new(code: Key::CHAR, char: bytes)
+        end
+      end
+
+      private
+
+      def parse_single(byte)
+        ord = byte.ord
+
+        case ord
+        when 13  # CR
+          KeyEvent.new(code: Key::ENTER)
+        when 9   # TAB
+          KeyEvent.new(code: Key::TAB)
+        when 127 # DEL (backspace on most terminals)
+          KeyEvent.new(code: Key::BACKSPACE)
+        when 8   # BS (backspace on some terminals)
+          KeyEvent.new(code: Key::BACKSPACE)
+        when 1..26
+          # Ctrl+A through Ctrl+Z
+          char = (ord + 96).chr # Convert to lowercase letter
+          KeyEvent.new(code: Key::CHAR, char: char, modifiers: Key::CTRL)
+        when 32..126
+          # Printable ASCII
+          KeyEvent.new(code: Key::CHAR, char: byte)
+        else
+          nil
+        end
+      end
+
+      def parse_escape(bytes)
+        return KeyEvent.new(code: Key::ESCAPE) if bytes == "\e"
+
+        case bytes
+        # SGR mouse: ESC [ < Cb ; Cx ; Cy M/m
+        when /\A\e\[<(\d+);(\d+);(\d+)([Mm])\z/
+          parse_sgr_mouse($1.to_i, $2.to_i, $3.to_i, $4)
+        # CSI sequences: ESC [ ...
+        when /\A\e\[([A-Za-z])\z/
+          parse_csi_letter($1)
+        when /\A\e\[(\d+)~\z/
+          parse_csi_tilde($1.to_i)
+        when /\A\e\[1;(\d+)([A-Za-z])\z/
+          parse_csi_modified($2, $1.to_i)
+        # Normal mouse: ESC [ M Cb Cx Cy (legacy, 3 raw bytes after M)
+        when /\A\e\[M(.{3})\z/m
+          parse_normal_mouse($1)
+        # SS3 sequences: ESC O ...
+        when /\A\eO([A-Za-z])\z/
+          parse_ss3($1)
+        # Alt+letter: ESC + letter
+        when /\A\e(.)\z/
+          KeyEvent.new(code: Key::CHAR, char: $1, modifiers: Key::ALT)
+        else
+          nil
+        end
+      end
+
+      # CSI single letter: ESC [ X
+      def parse_csi_letter(letter)
+        case letter
+        when "A" then KeyEvent.new(code: Key::UP)
+        when "B" then KeyEvent.new(code: Key::DOWN)
+        when "C" then KeyEvent.new(code: Key::RIGHT)
+        when "D" then KeyEvent.new(code: Key::LEFT)
+        when "H" then KeyEvent.new(code: Key::HOME)
+        when "F" then KeyEvent.new(code: Key::END_KEY)
+        when "Z" then KeyEvent.new(code: Key::BACKTAB)
+        else nil
+        end
+      end
+
+      # CSI tilde sequences: ESC [ N ~
+      def parse_csi_tilde(n)
+        case n
+        when 2  then KeyEvent.new(code: Key::INSERT)
+        when 3  then KeyEvent.new(code: Key::DELETE)
+        when 5  then KeyEvent.new(code: Key::PAGE_UP)
+        when 6  then KeyEvent.new(code: Key::PAGE_DOWN)
+        when 15 then KeyEvent.new(code: Key::F5)
+        when 17 then KeyEvent.new(code: Key::F6)
+        when 18 then KeyEvent.new(code: Key::F7)
+        when 19 then KeyEvent.new(code: Key::F8)
+        when 20 then KeyEvent.new(code: Key::F9)
+        when 21 then KeyEvent.new(code: Key::F10)
+        when 23 then KeyEvent.new(code: Key::F11)
+        when 24 then KeyEvent.new(code: Key::F12)
+        else nil
+        end
+      end
+
+      # CSI modified: ESC [ 1 ; MOD X (e.g., Shift+Up = ESC[1;2A)
+      def parse_csi_modified(letter, mod_code)
+        modifiers = decode_modifiers(mod_code)
+        base = parse_csi_letter(letter)
+        return nil unless base
+
+        KeyEvent.new(code: base.code, char: base.char, modifiers: modifiers)
+      end
+
+      # SS3 sequences: ESC O X (function keys on some terminals)
+      def parse_ss3(letter)
+        case letter
+        when "P" then KeyEvent.new(code: Key::F1)
+        when "Q" then KeyEvent.new(code: Key::F2)
+        when "R" then KeyEvent.new(code: Key::F3)
+        when "S" then KeyEvent.new(code: Key::F4)
+        when "H" then KeyEvent.new(code: Key::HOME)
+        when "F" then KeyEvent.new(code: Key::END_KEY)
+        else nil
+        end
+      end
+
+      # Decode xterm modifier parameter:
+      # 2=Shift, 3=Alt, 4=Shift+Alt, 5=Ctrl, 6=Shift+Ctrl, 7=Alt+Ctrl, 8=Shift+Alt+Ctrl
+      def decode_modifiers(code)
+        val = code - 1
+        mods = Key::NONE
+        mods |= Key::SHIFT if (val & 0b001) != 0
+        mods |= Key::ALT   if (val & 0b010) != 0
+        mods |= Key::CTRL  if (val & 0b100) != 0
+        mods
+      end
+
+      # SGR extended mouse mode: ESC [ < Cb ; Cx ; Cy M (press) or m (release)
+      # Cb encodes button + modifiers + drag flag
+      def parse_sgr_mouse(cb, cx, cy, terminator)
+        # Coordinates are 1-based in SGR mode
+        x = cx - 1
+        y = cy - 1
+
+        # Decode modifiers from cb
+        mods = Key::NONE
+        mods |= Key::SHIFT if (cb & 4) != 0
+        mods |= Key::ALT   if (cb & 8) != 0
+        mods |= Key::CTRL  if (cb & 16) != 0
+
+        is_drag = (cb & 32) != 0
+        is_release = terminator == "m"
+        button_bits = cb & 3
+        is_scroll = (cb & 64) != 0
+
+        if is_scroll
+          button = button_bits == 0 ? MouseEvent::SCROLL_UP : MouseEvent::SCROLL_DOWN
+          action = MouseEvent::PRESS
+        else
+          button = case button_bits
+                   when 0 then MouseEvent::LEFT
+                   when 1 then MouseEvent::MIDDLE
+                   when 2 then MouseEvent::RIGHT
+                   else MouseEvent::NONE
+                   end
+          action = if is_release
+                     MouseEvent::RELEASE
+                   elsif is_drag
+                     MouseEvent::DRAG
+                   else
+                     MouseEvent::PRESS
+                   end
+        end
+
+        MouseEvent.new(button: button, action: action, x: x, y: y, modifiers: mods)
+      end
+
+      # Legacy normal mouse: ESC [ M Cb Cx Cy (raw bytes, 32-based encoding)
+      def parse_normal_mouse(raw)
+        cb = raw.getbyte(0) - 32
+        x = raw.getbyte(1) - 33
+        y = raw.getbyte(2) - 33
+
+        mods = Key::NONE
+        mods |= Key::SHIFT if (cb & 4) != 0
+        mods |= Key::ALT   if (cb & 8) != 0
+        mods |= Key::CTRL  if (cb & 16) != 0
+
+        is_drag = (cb & 32) != 0
+        is_scroll = (cb & 64) != 0
+        button_bits = cb & 3
+
+        if is_scroll
+          button = button_bits == 0 ? MouseEvent::SCROLL_UP : MouseEvent::SCROLL_DOWN
+          action = MouseEvent::PRESS
+        elsif button_bits == 3
+          button = MouseEvent::NONE
+          action = MouseEvent::RELEASE
+        else
+          button = case button_bits
+                   when 0 then MouseEvent::LEFT
+                   when 1 then MouseEvent::MIDDLE
+                   when 2 then MouseEvent::RIGHT
+                   else MouseEvent::NONE
+                   end
+          action = is_drag ? MouseEvent::DRAG : MouseEvent::PRESS
+        end
+
+        MouseEvent.new(button: button, action: action, x: x, y: y, modifiers: mods)
+      end
+    end
+  end
+end

data/lib/rubytui/input/reader.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module RubyTUI
+  module Input
+    # Reads terminal input without blocking and decodes it with a {Parser}.
+    #
+    # A lone ESC byte is told apart from the start of an escape sequence by
+    # waiting up to {ESC_TIMEOUT_MS} for more bytes.
+    #
+    # @example
+    #   reader = Input::Reader.new
+    #   event = reader.poll(timeout_ms: 50)  # => KeyEvent, MouseEvent or nil
+    class Reader
+      # Timeout for disambiguating standalone ESC from escape sequences (ms)
+      ESC_TIMEOUT_MS = 50
+
+      # @param input [IO] input stream; must support <tt>IO.select</tt> and
+      #   +read_nonblock+ (default: +$stdin+)
+      def initialize(input: $stdin)
+        @input = input
+        @parser = Parser.new
+      end
+
+      # Poll for an event with the given timeout.
+      #
+      # @param timeout_ms [Integer] maximum time to wait for input, in milliseconds
+      #   (default: 100)
+      # @return [KeyEvent, MouseEvent, nil] the decoded event, or nil if no input
+      #   arrived within the timeout or the bytes read were not recognised
+      def poll(timeout_ms: 100)
+        timeout_sec = timeout_ms / 1000.0
+        ready = IO.select([@input], nil, nil, timeout_sec)
+        return nil unless ready
+
+        read_event
+      end
+
+      # Blocking read - waits indefinitely for an event.
+      #
+      # Calls {#poll} in a loop until it returns an event.
+      #
+      # @return [KeyEvent, MouseEvent] the next recognised event
+      def read
+        loop do
+          event = poll(timeout_ms: 1000)
+          return event if event
+        end
+      end
+
+      private
+
+      def read_event
+        # Read the first byte
+        first = read_byte
+        return nil unless first
+
+        if first == "\e"
+          # Could be standalone ESC or start of escape sequence.
+          # Wait briefly for more bytes.
+          if has_more_input?(ESC_TIMEOUT_MS)
+            bytes = first + read_available
+            @parser.parse(bytes)
+          else
+            @parser.parse("\e")
+          end
+        elsif first.ord < 128
+          @parser.parse(first)
+        else
+          # Multi-byte UTF-8: read continuation bytes
+          bytes = read_utf8(first)
+          @parser.parse(bytes)
+        end
+      end
+
+      def read_byte
+        @input.read_nonblock(1)
+      rescue IO::WaitReadable, EOFError
+        nil
+      end
+
+      def read_available
+        buf = String.new
+        loop do
+          byte = @input.read_nonblock(1)
+          buf << byte
+        rescue IO::WaitReadable, EOFError
+          break
+        end
+        buf
+      end
+
+      def has_more_input?(timeout_ms)
+        ready = IO.select([@input], nil, nil, timeout_ms / 1000.0)
+        !ready.nil?
+      end
+
+      # Read remaining bytes of a UTF-8 multibyte character
+      def read_utf8(first_byte)
+        ord = first_byte.ord
+        remaining = if ord >= 0xF0 then 3
+                    elsif ord >= 0xE0 then 2
+                    elsif ord >= 0xC0 then 1
+                    else 0
+                    end
+
+        bytes = first_byte
+        remaining.times do
+          b = read_byte
+          break unless b
+
+          bytes << b
+        end
+        bytes
+      end
+    end
+  end
+end

data/lib/rubytui/layout/constraint.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Layout
+    # A sizing rule for one segment of a {Layout} split.
+    #
+    # Create instances with the factory methods; {Layout#split} resolves them.
+    # Fixed constraints ({.length}, {.percentage}, {.ratio}) are allocated
+    # first, then the remaining space is shared among {.fill}, {.min} and
+    # {.max} constraints.
+    #
+    # @example Header, body and status line
+    #   layout = Layout::Layout.vertical([
+    #     Layout::Constraint.length(3),
+    #     Layout::Constraint.fill,
+    #     Layout::Constraint.length(1)
+    #   ])
+    #   header, body, status = layout.split(area)
+    class Constraint
+      attr_reader :kind, :value
+
+      # @param kind [Symbol] +:length+, +:percentage+, +:min+, +:max+, +:fill+ or +:ratio+
+      # @param value [Integer, Array(Integer, Integer)] size parameter; a
+      #   <tt>[num, den]</tt> pair for +:ratio+
+      def initialize(kind, value)
+        @kind = kind
+        @value = value
+      end
+
+      # Factory methods
+      class << self
+        # Fixed size, reduced if less space remains.
+        #
+        # @param n [Integer] size in cells
+        # @return [Constraint]
+        def length(n)         = new(:length, n)
+        # Percentage of the available space, rounded; reduced if less space remains.
+        #
+        # @param n [Numeric] percentage (0-100)
+        # @return [Constraint]
+        def percentage(n)     = new(:percentage, n)
+        # At least +n+ cells when space allows, plus a weight-1 share of the
+        # space left after fixed constraints.
+        #
+        # @param n [Integer] minimum size in cells
+        # @return [Constraint]
+        def min(n)            = new(:min, n)
+        # A weight-1 share of the space left after fixed constraints, capped
+        # at +n+ cells.
+        #
+        # @param n [Integer] maximum size in cells
+        # @return [Constraint]
+        def max(n)            = new(:max, n)
+        # A share of the space left after fixed constraints, proportional to
+        # +weight+ (+min+ and +max+ constraints count as weight 1).
+        #
+        # @param weight [Integer] relative weight (default: 1)
+        # @return [Constraint]
+        def fill(weight = 1)  = new(:fill, weight)
+        # Fraction <tt>num / den</tt> of the available space, rounded; reduced if
+        # less space remains.
+        #
+        # @param num [Integer] numerator
+        # @param den [Integer] denominator
+        # @return [Constraint]
+        def ratio(num, den)   = new(:ratio, [num, den].freeze)
+      end
+
+      # Value equality: same kind and value.
+      #
+      # @param other [Object] object to compare
+      # @return [Boolean] true if +other+ is a Constraint with equal {#kind} and {#value}
+      def ==(other)
+        other.is_a?(Constraint) && @kind == other.kind && @value == other.value
+      end
+
+      # @return [String] human-readable form, e.g. <tt>Constraint(length: 3)</tt>
+      def to_s = "Constraint(#{@kind}: #{@value})"
+      # @return [String] same as {#to_s}
+      def inspect = to_s
+    end
+  end
+end

data/lib/rubytui/layout/flex.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Layout
+    # Flex modes control how spare space is distributed when constraints
+    # don't perfectly consume the available area.
+    module Flex
+      START         = :start          # Pack items to start, spare space at end
+      END_POS       = :end            # Pack items to end, spare space at start
+      CENTER        = :center         # Center items, spare space split around edges
+      SPACE_BETWEEN = :space_between  # Distribute spare space between items
+      SPACE_AROUND  = :space_around   # Distribute spare space around items
+      STRETCH       = :stretch        # Stretch fill constraints to consume all space (default)
+    end
+  end
+end

data/lib/rubytui/layout/layout.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Constraint-based layout: {Layout::Layout} splits a {Rect} into rows or
+  # columns sized by {Constraint} objects and positioned by a {Flex} mode.
+  module Layout
+    # Splits a {Rect} along one axis into sub-rects sized by {Constraint}
+    # objects, with optional spacing between them.
+    #
+    # @example Sidebar and main area
+    #   sidebar, main = Layout::Layout.horizontal(
+    #     [Layout::Constraint.length(20), Layout::Constraint.fill]
+    #   ).split(area)
+    class Layout
+      # Split along the x axis into side-by-side columns.
+      HORIZONTAL = :horizontal
+      # Split along the y axis into stacked rows.
+      VERTICAL   = :vertical
+
+      attr_reader :direction, :constraints, :spacing, :flex
+
+      # @param direction [Symbol] {HORIZONTAL} or {VERTICAL}
+      # @param constraints [Array<Constraint>] one constraint per segment
+      # @param spacing [Integer] gap in cells between adjacent segments (default: 0)
+      # @param flex [Symbol] {Flex} mode for placing spare space (default: {Flex::STRETCH})
+      def initialize(direction:, constraints:, spacing: 0, flex: Flex::STRETCH)
+        @direction = direction
+        @constraints = constraints
+        @spacing = spacing
+        @flex = flex
+      end
+
+      class << self
+        # Build a {VERTICAL} layout (segments stacked top to bottom).
+        #
+        # @param constraints [Array<Constraint>] one constraint per segment
+        # @param spacing [Integer] gap in rows between adjacent segments (default: 0)
+        # @param flex [Symbol] {Flex} mode for placing spare space (default: {Flex::STRETCH})
+        # @return [Layout]
+        def vertical(constraints, spacing: 0, flex: Flex::STRETCH)
+          new(direction: VERTICAL, constraints: constraints, spacing: spacing, flex: flex)
+        end
+
+        # Build a {HORIZONTAL} layout (segments placed left to right).
+        #
+        # @param constraints [Array<Constraint>] one constraint per segment
+        # @param spacing [Integer] gap in columns between adjacent segments (default: 0)
+        # @param flex [Symbol] {Flex} mode for placing spare space (default: {Flex::STRETCH})
+        # @return [Layout]
+        def horizontal(constraints, spacing: 0, flex: Flex::STRETCH)
+          new(direction: HORIZONTAL, constraints: constraints, spacing: spacing, flex: flex)
+        end
+      end
+
+      # Split a Rect into sub-Rects according to constraints.
+      #
+      # Sizes are solved along {#direction} over the area's length minus the
+      # total spacing; the other dimension is taken from +area+. Space left
+      # unallocated is placed according to {#flex}.
+      #
+      # @param area [Rect] area to split
+      # @return [Array<Rect>] one Rect per constraint, in order (empty if there
+      #   are no constraints)
+      def split(area)
+        return [] if @constraints.empty?
+
+        total = @direction == HORIZONTAL ? area.width : area.height
+        total_spacing = @spacing * [@constraints.length - 1, 0].max
+        available = [total - total_spacing, 0].max
+
+        sizes = solve(available)
+        allocated = sizes.sum + total_spacing
+        spare = [total - allocated, 0].max
+
+        # Apply flex positioning
+        build_rects(area, sizes, spare)
+      end
+
+      private
+
+      def build_rects(area, sizes, spare)
+        n = sizes.length
+        rects = []
+
+        # Calculate gaps based on flex mode
+        leading, between, trailing = compute_flex_gaps(spare, n)
+
+        offset = leading
+        sizes.each_with_index do |size, i|
+          rect = if @direction == HORIZONTAL
+                   Rect.new(x: area.x + offset, y: area.y, width: size, height: area.height)
+                 else
+                   Rect.new(x: area.x, y: area.y + offset, width: area.width, height: size)
+                 end
+          rects << rect
+          offset += size + @spacing + (i < n - 1 ? between : 0)
+        end
+
+        rects
+      end
+
+      # Returns [leading_gap, between_gap, trailing_gap]
+      def compute_flex_gaps(spare, n)
+        return [0, 0, 0] if spare <= 0 || n <= 0
+
+        case @flex
+        when Flex::START, Flex::STRETCH
+          [0, 0, spare]
+        when Flex::END_POS
+          [spare, 0, 0]
+        when Flex::CENTER
+          half = spare / 2
+          [half, 0, spare - half]
+        when Flex::SPACE_BETWEEN
+          if n <= 1
+            [0, 0, spare]
+          else
+            gap = spare / (n - 1)
+            remainder = spare - gap * (n - 1)
+            [0, gap, -remainder]  # trailing absorbs rounding
+          end
+        when Flex::SPACE_AROUND
+          if n == 0
+            [spare, 0, 0]
+          else
+            # n items create n+1 gaps (before first, between each, after last)
+            # but space_around puts equal space on each side of each item
+            gap = spare / (n * 2)
+            remainder = spare - gap * n * 2
+            [gap + remainder / 2, gap * 2, gap + (remainder + 1) / 2]
+          end
+        else
+          [0, 0, spare]
+        end
+      end
+
+      # Two-pass constraint solver:
+      # Pass 1: Resolve fixed constraints (Length, Percentage, Ratio)
+      # Pass 2: Distribute remaining space to Fill, apply Min/Max clamping
+      def solve(total)
+        n = @constraints.length
+        sizes = Array.new(n, 0)
+        remaining = total
+        fill_indices = []
+
+        # Pass 1: Fixed allocations
+        @constraints.each_with_index do |c, i|
+          case c.kind
+          when :length
+            sizes[i] = [c.value, remaining].min
+            remaining -= sizes[i]
+          when :percentage
+            sizes[i] = [(total * c.value / 100.0).round, remaining].min
+            remaining -= sizes[i]
+          when :ratio
+            num, den = c.value
+            sizes[i] = [(total * num / den.to_f).round, remaining].min
+            remaining -= sizes[i]
+          when :min
+            sizes[i] = [c.value, remaining].min
+            remaining -= sizes[i]
+            fill_indices << i
+          when :max
+            fill_indices << i
+          when :fill
+            fill_indices << i
+          end
+        end
+
+        # Pass 2: Distribute remaining space among fill/min/max constraints
+        if fill_indices.any? && remaining > 0
+          total_weight = fill_indices.sum do |i|
+            c = @constraints[i]
+            c.kind == :fill ? c.value : 1
+          end
+
+          fill_indices.each do |i|
+            c = @constraints[i]
+            weight = c.kind == :fill ? c.value : 1
+            share = (remaining * weight / total_weight.to_f).round
+
+            case c.kind
+            when :fill
+              sizes[i] = share
+            when :min
+              sizes[i] = [sizes[i] + share, c.value].max
+            when :max
+              sizes[i] = [share, c.value].min
+            end
+          end
+
+          # Adjust rounding errors
+          allocated = sizes.sum
+          diff = total - allocated
+          if diff != 0 && fill_indices.any?
+            sizes[fill_indices.last] += diff
+          end
+        end
+
+        sizes.map! { |s| [s, 0].max }
+        sizes
+      end
+    end
+  end
+end