rubytui 1.2.3 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ec32a08aa7695cdc9b1db38895f10df4e37ff057dec2799b924fc2a6d8df860
-  data.tar.gz: 5a8a38833a21651b6372a420aea4be5e17b6f214653818b198c81303c45bf29d
+  metadata.gz: ac917512f05261231e65601213ab71f6205cd68818e3da3adb1f867c66759719
+  data.tar.gz: bbad14e5928bde95d26c6cfcf2143f68f228f51559519b68f1c83eae5dec1ced
 SHA512:
-  metadata.gz: b0c26618a8ab168de7278fb24d0234b332983e0426ec945c2bb92ddc69da270788fd6d20ac578d792e9ac2d04398f374912ac118ebb316fdcb85aeb517197f97
-  data.tar.gz: 00a6150cc97eca7ca31eead19b04c1bbb0426a2c794dbf5208657199cc0e298a8d445c29aaf015519d41793d93890862cad04755b4bc182dfd98bdfa633c09dd
+  metadata.gz: 11827373b3850a674cf837353c4a60c8927abe4da423e0dfff1c2b3ee39b1c733f211f209151446140b3a257a5033d9bfe50e69b9daa8eeb211db34a4d6496e1
+  data.tar.gz: a887bd14dbb30d02e9fd0801b2acbe56acb543dcf25e216a4cb7f23e580ae69dabc6d5d15e420b708c107d7b28ec00683a6efeeaef9a266cd57f005f8a317f24

data/README.md

@@ -1,6 +1,6 @@
 # RubyTUI
 
-RubyTUI is a terminal user interface library written in pure Ruby with no runtime dependencies. It provides immediate-mode rendering with double buffering, constraint-based layouts, built-in widgets, keyboard and mouse input, an optional Model-View-Update application framework, and inline images through the Kitty graphics protocol.
+RubyTUI is a terminal user interface library for Ruby with no runtime dependencies. It provides immediate-mode rendering with double buffering, constraint-based layouts, built-in widgets, keyboard and mouse input, an optional Model-View-Update application framework, and inline images through the Kitty graphics protocol.
 
 It is suited both to full-screen interactive applications and to command-line tools that only need styled, one-shot output such as tables, boxes and progress bars.
 
@@ -82,6 +82,8 @@ line = RubyTUI::Line.new([
 paragraph = RubyTUI::Widgets::Paragraph.new(text: line)
 ```
 
+Paragraph layers styles from the outside in: the paragraph's `style:`, then the `Text`'s style, then each `Line`'s, then each `Span`'s, with later ones winning.
+
 Colors are sent to the terminal exactly as specified. To support terminals with fewer colors, use `RubyTUI::ColorMode` to detect the capability and convert colors yourself:
 
 ```ruby
@@ -131,14 +133,14 @@ All built-in widgets live in `RubyTUI::Widgets`. Most accept a `block:` argument
 |--------|------|-------------|
 | `Block` | stateless | Borders on all or selected sides, title aligned left, center or right, padding, background style. `block.inner(area)` returns the area inside the borders and padding. |
 | `Paragraph` | stateless | Multi-line styled text with word, character or no wrapping, aligned left, center or right. |
-| `List` + `ListState` | stateful | Scrollable, selectable list with a highlight symbol and style; scrolls to keep the selection visible. |
-| `Table` + `TableState` | stateful | Rows with an optional header and separator, row selection, and fixed or equally divided column widths. |
+| `List` + `ListState` | stateful | Scrollable, selectable list with a highlight symbol and style; scrolls to keep the selection visible. `ListState.new(selected: nil)` shows no selection. |
+| `Table` + `TableState` | stateful | Rows with an optional header and separator, row selection, and fixed or equally divided column widths. `TableState.new(selected: nil)` shows no selection. |
 | `Gauge` | stateless | Horizontal progress bar with eighth-of-a-cell precision and a centered label (the percentage by default). |
 | `Sparkline` | stateless | Compact bar chart, one column per value, showing the most recent values that fit. |
-| `Scrollbar` | stateless | Vertical or horizontal scroll indicator with a proportional thumb and optional arrows. |
-| `Tabs` | stateless | Horizontal tab bar with active and inactive styles and a configurable divider. |
+| `Scrollbar` | stateless | Vertical or horizontal scroll indicator with a proportional thumb and optional arrows. `style:` is the base style; `track_style:` and `thumb_style:` are applied on top. |
+| `Tabs` | stateless | Horizontal tab bar with active and inactive styles, an optional `highlight_style:` applied on top of the active tab, and a configurable divider. |
 | `Canvas` | stateless | Points, lines and text labels in data coordinates, drawn with Braille characters (2x4 dots per cell). |
-| `Chart` + `Dataset` | stateless | Line chart of one or more datasets with optional labeled axes and fixed or data-derived bounds. Dataset names are not displayed. |
+| `Chart` + `Dataset` | stateless | Line chart of one or more datasets with optional labeled axes and fixed or data-derived bounds; `style:` sets the base style (e.g. background) of the whole chart. Dataset names are not displayed. |
 | `Popup` | stateless | Overlay that clears its area and draws a block and an optional shadow; sized in cells or as a percentage of the parent, centered or placed at a fixed position. `popup.inner(area)` returns its content area. |
 | `InputField` + `InputState` | stateful | Single-line text input with a cursor, horizontal scrolling and a placeholder. |
 | `Image` | stateless | PNG or raw RGBA image drawn with the Kitty graphics protocol. See [Images](#images). |
@@ -192,7 +194,7 @@ end
 
 ## Input
 
-`reader.poll(timeout_ms: 100)` waits up to the given time and returns a `RubyTUI::KeyEvent`, a `RubyTUI::MouseEvent`, or `nil` when no recognized input arrived. `reader.read` blocks until an event arrives.
+`reader.poll(timeout_ms: 100)` waits up to the given time and returns a `RubyTUI::KeyEvent`, a `RubyTUI::MouseEvent`, a `RubyTUI::ResizeEvent` (the terminal size changed since the previous call; it has `width` and `height`), or `nil` when no recognized input arrived. Replies that the terminal writes to the input, such as image acknowledgements, are ignored. `reader.read` blocks until an event arrives and raises `EOFError` once the input is closed; `reader.eof?` reports whether that has happened. At end of input, `poll` waits out its timeout and returns `nil`.
 
 ### Keyboard
 
@@ -265,8 +267,8 @@ end
 
 `RubyTUI.run(mouse: true)` enables reporting of button presses, releases, drags and the scroll wheel. A `MouseEvent` has:
 
-- `button`: `:left`, `:middle`, `:right`, `:scroll_up`, `:scroll_down` or `:none` (constants `RubyTUI::MouseEvent::LEFT` and so on)
-- `action`: `:press`, `:release` or `:drag` (scroll-wheel events are reported as `:press`)
+- `button`: `:left`, `:middle`, `:right`, `:scroll_up`, `:scroll_down`, `:scroll_left`, `:scroll_right` or `:none` (constants `RubyTUI::MouseEvent::LEFT` and so on)
+- `action`: `:press`, `:release` or `:drag` (scroll-wheel events are reported as `:press`). `:move`, pointer motion with no button held, is only reported if the terminal is switched to any-motion mode (1003), which `RubyTUI.run(mouse: true)` does not do.
 - `x`, `y`: zero-based cell coordinates
 - `ctrl?`, `alt?`, `shift?`
 
@@ -296,12 +298,12 @@ For structured applications, include `RubyTUI::App` and implement the hooks belo
 | Hook | Purpose |
 |------|---------|
 | `init` | Returns the initial model (any object; a Hash by default). |
-| `handle_event(event)` | Converts an input event into a message, or returns `nil` to ignore it. |
+| `handle_event(event)` | Converts an input event (`KeyEvent`, `MouseEvent` or `ResizeEvent`) into a message, or returns `nil` to ignore it. |
 | `handle_tick(model)` | Called after every poll, whether or not an event arrived; returns a message or `nil`. Use it for animations and periodic work. |
 | `update(model, msg)` | Returns the next model. Call `throw(:quit)` or `throw(:quit, value)` to leave the loop. |
 | `view(model, frame)` | Draws the model into the frame. |
 | `on_start(terminal, reader)` | Called once after `init`, before the loop starts. |
-| `on_stop(value)` | Called once after the loop ends and before the terminal is restored, with the value given to `throw(:quit, value)` (or `nil`). |
+| `on_stop(value)` | Called once after the loop ends and before the terminal is restored, with the value given to `throw(:quit, value)`, or the last model after a bare `throw(:quit)`. |
 
 ```ruby
 require "rubytui"
@@ -384,7 +386,7 @@ RubyTUI.print_gauge(ratio: 0.75, title: " Progress ", width: 40)
 ```
 
 - `print_table(header:, rows:, title:, border:, width:, ...)` also accepts `widths:`, `column_spacing:`, `header_style:`, `style:` and `border_style:`. The border is drawn only when `title:` is given.
-- `print_box(title:, content:, border:, width:, ...)` takes a string (split on newlines) or an array of lines, and also accepts `alignment:`, `text_style:`, `style:` and `border_style:`.
+- `print_box(title:, content:, border:, width:, ...)` takes a String (split on newlines), an Array of lines, or a `Text`, `Line` or `Span`; the box is as tall as the content after wrapping to the box width. It also accepts `alignment:`, `text_style:`, `style:` and `border_style:`.
 - `print_gauge(ratio:, label:, title:, width:, ...)` also accepts `gauge_style:`, `border:` and `border_style:`. The border is drawn only when `title:` is given.
 
 `border:` is one of `:rounded` (the default), `:light`, `:double`, `:thick` or `:plain`, or a `RubyTUI::Symbols` border set.
@@ -410,6 +412,7 @@ puts buf.to_ansi
 - PNG is sent to the terminal as is; its dimensions are read from the file header.
 - Raw 8-bit RGBA pixel data requires `format: :rgba` together with `pixel_width:` and `pixel_height:`.
 - JPEG, WebP, GIF and BMP data is detected and raises `RubyTUI::UnsupportedImageFormat`. Convert such images to PNG first, for example with ImageMagick: `system("magick", "input.jpg", "output.png")`.
+- Any other `format:` value raises `ArgumentError`.
 
 ```ruby
 # From a PNG file
@@ -481,9 +484,8 @@ image.ready?    # => true once the image can be drawn
 image.error?    # => true if the loader raised or returned unsupported data; see image.error
 ```
 
-- While loading, `Loading...` is drawn centered in the area; after a failure, `error_placeholder:` (default `[Error]`) is drawn.
-- `placeholder:` accepts a widget that includes `RubyTUI::Widget` (all built-in widgets do), which is drawn instead until the image is ready, or a string, which is shown before loading starts when `auto_start: false` is given. With `auto_start: false`, call `start_loading` to begin; `cancel` stops the loader thread.
-- `on_ready:` is called on the loader thread when the loader has returned (not on a cache hit); `on_error:` receives the exception raised by the loader.
+- Until the image is ready, `placeholder:` is drawn: a string is shown centered (`Loading...` if no placeholder is given), and a widget that includes `RubyTUI::Widget` (all built-in widgets do) is rendered in the area. After a failure, `error_placeholder:` (default `[Error]`) is drawn. With `auto_start: false`, call `start_loading` to begin; `cancel` stops the loader thread.
+- `on_ready:` is called on the loader thread once the image is ready (not on a cache hit); an exception it raises does not change the widget's state. `on_error:` receives the exception when the loader raises or returns data that is not a supported image (including `nil`); such data is not cached.
 - `cache:` (a Hash shared between instances) and `key:` reuse loaded data: when the cache already holds the key, the widget is ready immediately and the loader is not called.
 - `block:`, `style:` and `cell_size:` work as for `Image`.
 

data/lib/rubytui/app.rb

@@ -109,9 +109,9 @@ module RubyTUI
     #
     # Called before the terminal is restored.
     #
-    # @param model [Object, nil] the result of the <tt>catch(:quit)</tt> block:
-    #   the value passed as <tt>throw(:quit, value)</tt>, or nil for a bare
-    #   <tt>throw(:quit)</tt>
+    # @param model [Object] the value passed as <tt>throw(:quit, value)</tt>,
+    #   or the last model returned by {#init} or {#update} for a bare
+    #   <tt>throw(:quit)</tt> or <tt>throw(:quit, nil)</tt>
     # @return [void]
     def on_stop(model)
     end
@@ -119,7 +119,9 @@ module RubyTUI
     # Run the application.
     #
     # The main loop renders, polls for events, and dispatches messages.
-    # Call <tt>throw(:quit)</tt> from {#update} to exit the loop cleanly.
+    # Call <tt>throw(:quit)</tt> from {#update} to exit the loop cleanly;
+    # {#on_stop} then receives the last model, or +value+ for
+    # <tt>throw(:quit, value)</tt>.
     #
     # Wraps {RubyTUI.run} (raw mode, hidden cursor, alternate screen), so
     # the terminal is restored when the loop exits or raises. Each
@@ -138,7 +140,7 @@ module RubyTUI
         model = init
         on_start(terminal, reader)
 
-        model = catch(:quit) do
+        quit_value = catch(:quit) do
           loop do
             terminal.draw do |frame|
               view(model, frame)
@@ -156,7 +158,7 @@ module RubyTUI
           end
         end
 
-        on_stop(model)
+        on_stop(quit_value.nil? ? model : quit_value)
       end
     end
 

data/lib/rubytui/backends/ansi_backend.rb

@@ -64,7 +64,7 @@ module RubyTUI
         @buffer << cell.symbol
 
         # Wide characters advance terminal cursor by 2
-        w = cell.symbol.length == 1 ? Buffer.char_width(cell.symbol) : 1
+        w = cell.symbol.length == 1 ? Unicode.char_width(cell.symbol) : 1
         last_x = x + w - 1
         last_y = y
       end
@@ -167,17 +167,18 @@ module RubyTUI
     # Restore the input's terminal state saved by {#enable_raw_mode}.
     #
     # Runs +stty+ with the saved state on the input. Falls back to
-    # +cooked!+ (when the input supports it) if no state was saved or
-    # +stty+ raises.
+    # +cooked!+ (when the input supports it) if no state was saved, or
+    # +stty+ raises, exits non-zero or cannot be run.
     #
     # @return [void]
     def disable_raw_mode
       if @original_state
-        begin
+        restored = begin
           system("stty", @original_state, in: @input, err: File::NULL)
         rescue StandardError
-          @input.cooked! if @input.respond_to?(:cooked!)
+          false
         end
+        @input.cooked! if !restored && @input.respond_to?(:cooked!)
         @original_state = nil
       elsif @input.respond_to?(:cooked!)
         @input.cooked!
@@ -199,37 +200,41 @@ module RubyTUI
     #
     # Sends CSI 16 t and parses the response. Must be called before
     # entering raw mode or while in raw mode with careful stdin handling.
-    # Falls back to [9, 18] when the terminal does not answer within 100 ms
-    # or the query raises +IOError+, +Errno::EIO+ or +Errno::ENOTTY+; the
-    # result, including the fallback, is cached.
+    # Falls back to [9, 18] when the terminal does not answer within 100 ms,
+    # the query raises +IOError+, +Errno::EIO+ or +Errno::ENOTTY+, or the
+    # input does not support raw mode (e.g. a StringIO; no query is sent);
+    # the result, including the fallback, is cached.
     #
     # @return [Array(Integer, Integer)] cell dimensions [width_px, height_px]
     def query_cell_pixel_size
       return @cell_pixel_size if @cell_pixel_size
 
-      begin
-        @input.raw do
-          @output.write("\e[16t")
-          @output.flush
-
-          response = +""
-          deadline = Time.now + 0.1
-
-          while Time.now < deadline
-            if IO.select([@input], nil, nil, 0.01)
-              char = @input.read_nonblock(1, exception: false)
-              break if char == :wait_readable || char.nil?
-              response << char
-              break if char == "t"
+      # Inputs without raw mode (e.g. StringIO) cannot read the reply
+      if @input.respond_to?(:raw)
+        begin
+          @input.raw do
+            @output.write("\e[16t")
+            @output.flush
+
+            response = +""
+            deadline = Time.now + 0.1
+
+            while Time.now < deadline
+              if IO.select([@input], nil, nil, 0.01)
+                char = @input.read_nonblock(1, exception: false)
+                break if char == :wait_readable || char.nil?
+                response << char
+                break if char == "t"
+              end
             end
-          end
 
-          if response =~ /\e\[6;(\d+);(\d+)t/
-            @cell_pixel_size = [$2.to_i, $1.to_i]
+            if response =~ /\e\[6;(\d+);(\d+)t/
+              @cell_pixel_size = [$2.to_i, $1.to_i]
+            end
           end
+        rescue IOError, Errno::EIO, Errno::ENOTTY
+          # Terminal doesn't support query
         end
-      rescue IOError, Errno::EIO, Errno::ENOTTY
-        # Terminal doesn't support query
       end
 
       @cell_pixel_size ||= [9, 18]

data/lib/rubytui/buffer.rb

@@ -273,9 +273,8 @@ module RubyTUI
       prev_style = nil
 
       @area.height.times do |row|
-        # Build the row content and track the last non-empty column
+        # Build the row content
         row_buf = String.new(capacity: @area.width * 2)
-        last_styled_col = -1
         col = 0
         display_col = 0  # track actual terminal column for cursor correction
 
@@ -298,11 +297,6 @@ module RubyTUI
 
           row_buf << cell.symbol
 
-          # Track last non-default cell for trimming
-          unless cell.empty?
-            last_styled_col = col
-          end
-
           w = Unicode.string_width(cell.symbol)
           display_col += w
           col += [w, 1].max

data/lib/rubytui/errors.rb

@@ -4,8 +4,10 @@ module RubyTUI
   # Base class for all RubyTUI-specific errors.
   class Error < StandardError; end
   # Error category for terminal-related failures.
+  # @deprecated Never raised by RubyTUI; will be removed in 2.0.
   class TerminalError < Error; end
   # Error category for layout-related failures.
+  # @deprecated Never raised by RubyTUI; will be removed in 2.0.
   class LayoutError < Error; end
   # Raised by {Widgets::Image} when given image data in a format the Kitty
   # graphics protocol path does not accept (JPEG, WebP, GIF or BMP).

data/lib/rubytui/event.rb

@@ -17,7 +17,8 @@ module RubyTUI
 
     # @param code [Symbol] key code, one of the {Input::Key} key-code constants
     #   (e.g. {Input::Key::ENTER}, {Input::Key::CHAR})
-    # @param char [String, nil] the character, for {Input::Key::CHAR} events (default: nil)
+    # @param char [String, nil] the character, for {Input::Key::CHAR} events; a
+    #   UTF-8 String when produced by {Input::Parser} (default: nil)
     # @param modifiers [Integer] bitmask of {Input::Key::SHIFT}, {Input::Key::ALT} and
     #   {Input::Key::CTRL} (default: {Input::Key::NONE})
     def initialize(code:, char: nil, modifiers: Input::Key::NONE)
@@ -75,6 +76,10 @@ module RubyTUI
     SCROLL_UP   = :scroll_up
     # Scroll wheel down (reported with action {PRESS}).
     SCROLL_DOWN = :scroll_down
+    # Horizontal scroll left, wheel button 6 (reported with action {PRESS}).
+    SCROLL_LEFT = :scroll_left
+    # Horizontal scroll right, wheel button 7 (reported with action {PRESS}).
+    SCROLL_RIGHT = :scroll_right
     # No specific button (legacy-protocol release, or motion with no button held).
     NONE      = :none
 
@@ -86,9 +91,11 @@ module RubyTUI
     PRESS   = :press
     # Button released.
     RELEASE = :release
-    # Pointer motion reported by the terminal (motion flag set).
+    # Pointer motion with a button held.
     DRAG    = :drag
-    # Pointer motion with no button held. Currently never emitted by {Input::Parser}.
+    # Pointer motion with no button held (button {NONE}). Terminals report it
+    # only in any-event tracking (mode 1003), which
+    # {AnsiBackend#enable_mouse} does not turn on.
     MOVE    = :move
 
     # @!endgroup
@@ -96,7 +103,7 @@ module RubyTUI
     attr_reader :button, :action, :x, :y, :modifiers
 
     # @param button [Symbol] button constant ({LEFT}, {MIDDLE}, {RIGHT},
-    #   {SCROLL_UP}, {SCROLL_DOWN} or {NONE})
+    #   {SCROLL_UP}, {SCROLL_DOWN}, {SCROLL_LEFT}, {SCROLL_RIGHT} or {NONE})
     # @param action [Symbol] action constant ({PRESS}, {RELEASE}, {DRAG} or {MOVE})
     # @param x [Integer] column (0-based cell coordinate)
     # @param y [Integer] row (0-based cell coordinate)
@@ -144,6 +151,9 @@ module RubyTUI
   end
 
   # A terminal resize event carrying the new size in cells.
+  #
+  # {Input::Reader#poll} and {Input::Reader#read} return one when the size of
+  # the input terminal has changed since the previous call.
   class ResizeEvent < Event
     attr_reader :width, :height
 

data/lib/rubytui/input/parser.rb

@@ -5,36 +5,224 @@ module RubyTUI
     # 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),
+    # single UTF-8 characters (as raw bytes, as read by {Reader}, or as a UTF-8
+    # String), 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>),
+    # the same key sequences preceded by ESC (Alt+key as sent by rxvt-style
+    # terminals, e.g. <tt>ESC ESC [ A</tt> is Alt+Up),
     # and SGR and legacy mouse reports.
     #
+    # String sequences that terminals send as replies are recognised and
+    # produce no event: APC (<tt>ESC _</tt>, e.g. Kitty graphics responses),
+    # OSC (<tt>ESC ]</tt>), DCS (<tt>ESC P</tt>), SOS (<tt>ESC X</tt>) and PM
+    # (<tt>ESC ^</tt>), each ended by ST (ESC and a backslash) or BEL. Because these
+    # introducers start a string, Alt+P, Alt+X, Alt+], Alt+^ and Alt+_ are
+    # reported only when the input ends with the string they start still
+    # unfinished (see {#parse_prefix}).
+    #
+    # The +char+ of every {KeyEvent} it returns is a UTF-8 String.
+    #
     # @example
     #   Input::Parser.new.parse("\e[A")  # => KeyEvent(up)
     class Parser
+      # Longest CSI sequence, in bytes from ESC to the final byte. Recognised
+      # keys and SGR mouse reports are far shorter; the limit only bounds the
+      # bytes scanned for a final byte.
+      MAX_CSI_BYTES = 256
+      private_constant :MAX_CSI_BYTES
+
+      # Second byte of ESC P (DCS), ESC X (SOS), ESC ] (OSC), ESC ^ (PM) and
+      # ESC _ (APC), which start string sequences
+      STRING_INTRODUCERS = [0x50, 0x58, 0x5D, 0x5E, 0x5F].freeze
+      private_constant :STRING_INTRODUCERS
+
       # Parse raw bytes into an Event.
       #
+      # Input in any encoding is decoded byte-wise; a character is returned as
+      # UTF-8. Bytes that are not valid UTF-8 yield nil instead of raising.
+      #
       # @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
+      #   is nil, empty, invalid UTF-8 or not a recognised sequence
+      # @see #parse_prefix
       def parse(bytes)
         return nil if bytes.nil? || bytes.empty?
 
+        bytes = bytes.b
         # ESC sequence
         if bytes.start_with?("\e")
           parse_escape(bytes)
-        elsif bytes.length == 1
+        elsif bytes.bytesize == 1
           parse_single(bytes)
         else
           # Multi-byte UTF-8 character
-          KeyEvent.new(code: Key::CHAR, char: bytes)
+          char = utf8_char(bytes)
+          char && KeyEvent.new(code: Key::CHAR, char: char)
         end
       end
 
+      # Parse the first event at the front of a buffer that may hold several.
+      #
+      # Finds where the first key press, escape sequence or mouse report in
+      # +bytes+ ends and decodes it with {#parse}. Unrecognised sequences are
+      # still measured, so the caller can drop them and carry on.
+      #
+      # A CSI sequence (<tt>ESC [</tt>) is at most 256 bytes long. If no
+      # final byte comes within its first 256 bytes, only <tt>ESC [</tt> is
+      # taken, as Alt+[, and the bytes after it are left to be decoded as
+      # input of their own; this does not depend on +partial+.
+      #
+      # A terminal string sequence (APC, OSC, DCS, SOS, PM) runs up to and
+      # including its ST or BEL terminator and gives no event. An ESC inside
+      # it that does not start ST ends it just before that ESC, also with no
+      # event. There is no length limit ({Reader} applies one).
+      #
+      # @param bytes [String] buffered raw input
+      # @param partial [Boolean] true if more input may follow +bytes+: an
+      #   incomplete sequence at the front (such as a lone ESC, an unfinished
+      #   string sequence, or ESC ESC that may start Alt+key) is then left
+      #   unconsumed. When false, it is decoded as it stands: ESC ESC is a
+      #   plain ESC key; an unfinished string sequence (no terminator, and no
+      #   ESC followed by another byte) is taken to be typed, so only its
+      #   introducer is taken, as Alt+character (2 bytes, e.g. <tt>ESC P</tt>
+      #   is Alt+P), and the bytes after it are left to be decoded as input
+      #   of their own; any other unfinished sequence is taken whole (a lone
+      #   ESC is the ESC key, <tt>ESC [</tt> and <tt>ESC O</tt> are Alt+[ and
+      #   Alt+O, and a cut-off UTF-8 character, mouse report or longer CSI
+      #   sequence gives no event) (default: false)
+      # @return [Array(Event, Integer)] a two-element array: the event (nil if
+      #   the sequence was not recognised or is a string sequence) and the
+      #   number of bytes it took up. The count is 0 only when +bytes+ is
+      #   empty or, with +partial+, holds just the start of a sequence.
+      #
+      # @example
+      #   Input::Parser.new.parse_prefix("\e[A\e[B")  # => [KeyEvent(up), 3]
+      #   Input::Parser.new.parse_prefix("\e_Gi=1;OK\e\\q")  # => [nil, 11]
+      #   Input::Parser.new.parse_prefix("\ePab")  # => [KeyEvent(Alt+P), 2]
+      def parse_prefix(bytes, partial: false)
+        bytes = bytes.b unless bytes.encoding == Encoding::BINARY
+        length = sequence_length(bytes)
+        length ||= partial ? 0 : incomplete_length(bytes)
+        return [nil, 0] if length.zero?
+
+        [parse(bytes.byteslice(0, length)), length]
+      end
+
       private
 
+      # Byte length of the first sequence in +bytes+ (binary), 0 if empty,
+      # or nil if +bytes+ ends before the sequence is complete.
+      def sequence_length(bytes)
+        return 0 if bytes.empty?
+
+        first = bytes.getbyte(0)
+        if first == 0x1B
+          escape_length(bytes)
+        elsif first < 0x80
+          1
+        else
+          utf8_length(bytes, 0)
+        end
+      end
+
+      # Length to take for a sequence cut short by the end of input: all of
+      # it, except that ESC ESC starts with a plain ESC key and an unfinished
+      # string sequence with its introducer (Alt+character).
+      def incomplete_length(bytes)
+        return 1 if bytes.start_with?("\e\e")
+        return 2 if bytes.getbyte(0) == 0x1B && STRING_INTRODUCERS.include?(bytes.getbyte(1))
+
+        bytes.bytesize
+      end
+
+      def escape_length(bytes)
+        second = bytes.getbyte(1)
+        case second
+        when nil then nil   # lone ESC so far
+        when 0x1B then alt_sequence_length(bytes)
+        when *STRING_INTRODUCERS
+          string_length(bytes)
+        when 0x5B           # CSI: ESC [
+          third = bytes.getbyte(2)
+          if third.nil?
+            nil
+          elsif third == 0x4D # legacy mouse: ESC [ M Cb Cx Cy
+            bytes.bytesize >= 6 ? 6 : nil
+          else
+            csi_length(bytes)
+          end
+        when 0x4F           # SS3: ESC O X
+          bytes.bytesize >= 3 ? 3 : nil
+        else                # Alt+character
+          return 2 if second < 0x80
+
+          char_length = utf8_length(bytes, 1)
+          char_length && char_length + 1
+        end
+      end
+
+      # CSI: parameter/intermediate bytes 0x20-0x3F, then a final byte 0x40-0x7E.
+      # Any other byte ends a malformed sequence just before it. With no
+      # final byte within MAX_CSI_BYTES, ESC [ alone (Alt+[).
+      def csi_length(bytes)
+        (2...[bytes.bytesize, MAX_CSI_BYTES].min).each do |i|
+          b = bytes.getbyte(i)
+          return i + 1 if b.between?(0x40, 0x7E)
+          return i unless b.between?(0x20, 0x3F)
+        end
+        bytes.bytesize >= MAX_CSI_BYTES ? 2 : nil
+      end
+
+      # ESC ESC: both ESCs and the CSI or SS3 sequence after the second, if
+      # together they are a key (Alt+key); otherwise 1, the first ESC as a
+      # plain key.
+      def alt_sequence_length(bytes)
+        rest = bytes.byteslice(1..)
+        return 1 unless [nil, 0x5B, 0x4F].include?(rest.getbyte(1))
+
+        length = escape_length(rest)
+        return nil if length.nil?
+
+        parse(bytes.byteslice(0, length + 1)).is_a?(KeyEvent) ? length + 1 : 1
+      end
+
+      # String sequence: ends after BEL or ST (ESC \), or just before any other
+      # ESC; nil while no terminator or other ESC has come.
+      def string_length(bytes)
+        stop = bytes.index(/[\a\e]/, 2)
+        return nil if stop.nil?
+        return stop + 1 if bytes.getbyte(stop) == 0x07
+
+        following = bytes.getbyte(stop + 1)
+        return nil if following.nil? # ESC at the end: may be the start of ST
+
+        following == 0x5C ? stop + 2 : stop
+      end
+
+      # Length of the UTF-8 character starting at +start+; an invalid sequence
+      # ends just before the first byte that does not continue it.
+      def utf8_length(bytes, start)
+        need = case bytes.getbyte(start)
+               when 0xC2..0xDF then 2
+               when 0xE0..0xEF then 3
+               when 0xF0..0xF4 then 4
+               else 1
+               end
+        (1...need).each do |k|
+          b = bytes.getbyte(start + k)
+          return nil if b.nil?
+          return k unless b.between?(0x80, 0xBF)
+        end
+        need
+      end
+
+      # +raw+ as a UTF-8 String if it is exactly one valid character, else nil.
+      def utf8_char(raw)
+        char = String.new(raw, encoding: Encoding::UTF_8)
+        char if char.valid_encoding? && char.length == 1
+      end
+
       def parse_single(byte)
         ord = byte.ord
 
@@ -49,11 +237,11 @@ module RubyTUI
           KeyEvent.new(code: Key::BACKSPACE)
         when 1..26
           # Ctrl+A through Ctrl+Z
-          char = (ord + 96).chr # Convert to lowercase letter
+          char = (ord + 96).chr(Encoding::UTF_8) # 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)
+          KeyEvent.new(code: Key::CHAR, char: utf8_char(byte))
         else
           nil
         end
@@ -79,9 +267,16 @@ module RubyTUI
         # 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)
+        # Alt+key (rxvt-style): ESC + CSI or SS3 key sequence
+        when /\A\e(\e[\[O].+)\z/m
+          key = parse_escape($1)
+          if key.is_a?(KeyEvent)
+            KeyEvent.new(code: key.code, char: key.char, modifiers: key.modifiers | Key::ALT)
+          end
+        # Alt+character: ESC + one (possibly multi-byte) character
+        when /\A\e(.+)\z/
+          char = utf8_char($1)
+          char && KeyEvent.new(code: Key::CHAR, char: char, modifiers: Key::ALT)
         else
           nil
         end
@@ -154,7 +349,7 @@ module RubyTUI
       end
 
       # SGR extended mouse mode: ESC [ < Cb ; Cx ; Cy M (press) or m (release)
-      # Cb encodes button + modifiers + drag flag
+      # Cb encodes button + modifiers + motion flag
       def parse_sgr_mouse(cb, cx, cy, terminator)
         # Coordinates are 1-based in SGR mode
         x = cx - 1
@@ -172,8 +367,12 @@ module RubyTUI
         is_scroll = (cb & 64) != 0
 
         if is_scroll
-          button = button_bits == 0 ? MouseEvent::SCROLL_UP : MouseEvent::SCROLL_DOWN
+          button = scroll_button(button_bits)
           action = MouseEvent::PRESS
+        elsif is_drag && button_bits == 3
+          # Motion with no button held
+          button = MouseEvent::NONE
+          action = MouseEvent::MOVE
         else
           button = case button_bits
                    when 0 then MouseEvent::LEFT
@@ -209,11 +408,12 @@ module RubyTUI
         button_bits = cb & 3
 
         if is_scroll
-          button = button_bits == 0 ? MouseEvent::SCROLL_UP : MouseEvent::SCROLL_DOWN
+          button = scroll_button(button_bits)
           action = MouseEvent::PRESS
         elsif button_bits == 3
+          # Release, or motion with no button held
           button = MouseEvent::NONE
-          action = MouseEvent::RELEASE
+          action = is_drag ? MouseEvent::MOVE : MouseEvent::RELEASE
         else
           button = case button_bits
                    when 0 then MouseEvent::LEFT
@@ -226,6 +426,16 @@ module RubyTUI
 
         MouseEvent.new(button: button, action: action, x: x, y: y, modifiers: mods)
       end
+
+      # Wheel button for the low two bits of a wheel report (codes 64-67)
+      def scroll_button(button_bits)
+        case button_bits
+        when 0 then MouseEvent::SCROLL_UP
+        when 1 then MouseEvent::SCROLL_DOWN
+        when 2 then MouseEvent::SCROLL_LEFT
+        else MouseEvent::SCROLL_RIGHT
+        end
+      end
     end
   end
 end