rubytui 1.2.6 → 1.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c02474959ea48e1132fe6eb9d4928bfd903380165103601f7af0f4de781fcd2
-  data.tar.gz: b341e4db0fe3e8804415b3436418b9289882bece33a49a6912499854e286c58d
+  metadata.gz: 79cdd36b58280934698cfd3e90ff14ba85665e495826dfbbc350efa038177f06
+  data.tar.gz: a4304020e612c2d330cfd9aae0284e3780c7bed6c6b054e913f1e4330a38aa97
 SHA512:
-  metadata.gz: e7c0955376bb8cce509abcb7d17caf24d18b94c1e72931ace799d36307290a1432786cc4428a89163c6482b14cfdc3b7a07833ad9a5783fb33b16040c0af9cf7
-  data.tar.gz: 2ceee4bcd1442108229131a7fbd5d5f36a8617185224e67bc4ac6393d59608003edbd873a6daaf904d4b1af3449fc46aab2d96cc19ba8981dc1e9f5c68eadb02
+  metadata.gz: f56ab22ff3594c7f6c634017342e24ddb16fcaa59d76c3e3dc28b4e6be5d47142009f24d8e96f7135e291e0acb0051a838de0b8e7a248e5a33f9751520d8a82f
+  data.tar.gz: b3c031a1efcc1bc437f787bf88ea388a9ba7c3717b5bc57f739af2f3c245405fac6cc0048937768dcd716e670cb61ea01176df07b5e760e09fff68d2dc69806a

data/README.md

@@ -198,13 +198,25 @@ end
 
 ### Keyboard
 
-A `KeyEvent` has a `code`, a `char` and modifier predicates (`ctrl?`, `alt?`, `shift?`).
+A `KeyEvent` has a `code`, a `char` and modifier predicates (`ctrl?`, `alt?`, `shift?`, `super?`).
 
 - `code` is one of the symbols in `RubyTUI::Input::Key`: `CHAR`, `ENTER`, `ESCAPE`, `BACKSPACE`, `DELETE`, `TAB`, `BACKTAB` (Shift+Tab), `UP`, `DOWN`, `LEFT`, `RIGHT`, `HOME`, `END_KEY`, `PAGE_UP`, `PAGE_DOWN`, `INSERT` and `F1` to `F12`.
-- For `CHAR` events, `char` holds the character. Ctrl+letter arrives as the lowercase letter with `ctrl?` true, except Ctrl+H, Ctrl+I and Ctrl+M, which the terminal sends as Backspace, Tab and Enter. Alt+key arrives with `alt?` true.
-- Arrow keys, Home and End also report Shift, Alt and Ctrl modifiers.
+- For `CHAR` events, `char` holds the character. Ctrl+letter arrives as the lowercase letter with `ctrl?` true, except Ctrl+H, Ctrl+I and Ctrl+M, which the terminal sends as Backspace, Tab and Enter. Ctrl+Space arrives as `" "` with `ctrl?` true. Alt+key arrives with `alt?` true, including Alt+Backspace, Alt+Enter, Alt+Tab and Alt+Escape as those keys.
+- Arrow keys, Home, End, Page Up, Page Down, Insert, Delete and the function keys also report Shift, Alt and Ctrl modifiers.
 - A lone Escape key press is reported after a 50 ms wait that separates it from escape sequences.
 - In raw mode, Ctrl+C does not send `SIGINT`; it arrives as a key event, so handle it if your application should quit on it.
+- On macOS, Option types characters (Option+A gives `å`) unless the terminal is set to send it as Alt: `macos-option-as-alt` in Ghostty, Option key "Esc+" in iTerm2's profile, "Use Option as Meta key" in Terminal.
+
+#### Kitty keyboard protocol
+
+`RubyTUI.run(kitty_keyboard: true)` (also `RubyTUI.init` and `App#run!`) asks the terminal to report keys with the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), and switches it back off when the block exits or raises. On terminals that support it, such as Ghostty, iTerm2, kitty, Alacritty and foot:
+
+- Ctrl+Shift+letter arrives with `ctrl?` and `shift?` true, and `char` is the shifted character (`"A"`) when the terminal reports it, otherwise the lowercase letter.
+- Ctrl+I, Ctrl+M, Ctrl+H and Ctrl+[ arrive as Ctrl+letter, not as Tab, Enter, Backspace and Escape.
+- Ctrl and Alt combine with digits and punctuation, and Cmd combinations that the terminal does not use itself arrive with `super?` true.
+- Escape is reported without the 50 ms wait.
+
+Plain and Shift-ed text, Enter, Tab and Backspace arrive as before, as do all keys on terminals without the protocol, such as macOS Terminal. Shift+Space is not reported separately.
 
 ```ruby
 require "rubytui"
@@ -243,7 +255,7 @@ end
 
 ### Text input
 
-`InputState#handle_key(event)` applies a key event to the input and returns `true` if it consumed the event. Printable characters are inserted; Backspace, Delete, Left, Right, Home and End edit and move the cursor; Ctrl+A and Ctrl+E move to the start and end; Ctrl+K and Ctrl+U delete to the end and to the start; Ctrl+W deletes the previous word. Other keys, such as Enter, Tab and Escape, are left to your application.
+`InputState#handle_key(event)` applies a key event to the input and returns `true` if it consumed the event. Printable characters are inserted; Backspace, Delete, Left, Right, Home and End edit and move the cursor, treating a letter with its combining marks or an emoji sequence as one character; Ctrl+A and Ctrl+E move to the start and end; Ctrl+K and Ctrl+U delete to the end and to the start; Ctrl+W deletes the previous word. Other keys, such as Enter, Tab and Escape, are left to your application.
 
 ```ruby
 state = RubyTUI::Widgets::InputState.new

data/lib/rubytui/app.rb

@@ -134,9 +134,12 @@ module RubyTUI
     #   milliseconds (default: 50)
     # @param output [IO] output stream (default: $stdout)
     # @param input [IO] input stream (default: $stdin)
+    # @param kitty_keyboard [Boolean] report keys with the kitty keyboard
+    #   protocol where the terminal supports it (see {RubyTUI.run}) (default: false)
     # @return [void]
-    def run!(mouse: false, tick_ms: 50, output: $stdout, input: $stdin)
-      RubyTUI.run(output: output, input: input, mouse: mouse) do |terminal, reader|
+    def run!(mouse: false, tick_ms: 50, output: $stdout, input: $stdin, kitty_keyboard: false)
+      RubyTUI.run(output: output, input: input, mouse: mouse,
+                  kitty_keyboard: kitty_keyboard) do |terminal, reader|
         model = init
         on_start(terminal, reader)
 

data/lib/rubytui/backend.rb

@@ -116,6 +116,19 @@ module RubyTUI
       raise NotImplementedError
     end
 
+    # Turn on the kitty keyboard protocol (see {AnsiBackend#enable_kitty_keyboard}).
+    # No-op by default.
+    # @return [void]
+    def enable_kitty_keyboard
+      # no-op by default
+    end
+
+    # Turn off what {#enable_kitty_keyboard} turned on. No-op by default.
+    # @return [void]
+    def disable_kitty_keyboard
+      # no-op by default
+    end
+
     # Draw an image using the Kitty graphics protocol.
     # No-op by default; backends that support images override it.
     # @param placement [Hash{Symbol => Object}] image placement data with keys

data/lib/rubytui/backends/ansi_backend.rb

@@ -7,7 +7,8 @@ module RubyTUI
   #
   # Output accumulates in an internal string buffer and is written to the
   # output IO only by {#flush}. {#enter_alternate_screen},
-  # {#leave_alternate_screen}, {#enable_mouse}, {#disable_mouse} and
+  # {#leave_alternate_screen}, {#enable_mouse}, {#disable_mouse},
+  # {#enable_kitty_keyboard}, {#disable_kitty_keyboard} and
   # {#clear_all_images!} flush immediately.
   #
   # @see RubyTUI.init
@@ -17,6 +18,10 @@ module RubyTUI
     # Control Sequence Introducer (<tt>ESC [</tt>) that prefixes escape sequences.
     CSI = "\e["
 
+    # Kitty keyboard protocol flags pushed by {#enable_kitty_keyboard}:
+    # disambiguate escape codes (1) and report alternate keys (4).
+    KITTY_KEYBOARD_FLAGS = 0b101
+
     # @param output [IO] stream escape sequences are written to (default: $stdout)
     # @param input [IO] terminal input used for raw mode and cell-size queries
     #   (default: $stdin)
@@ -144,6 +149,40 @@ module RubyTUI
       flush
     end
 
+    # Push {KITTY_KEYBOARD_FLAGS} onto the terminal's kitty keyboard mode
+    # stack (<tt>CSI > 5 u</tt>) and flush. Keys the legacy encoding cannot
+    # tell apart then arrive as <tt>CSI u</tt> sequences, which {Input::Parser}
+    # decodes: Esc, and Ctrl, Alt or Super (Cmd) with a key. Plain and
+    # Shift-ed text, Enter, Tab and Backspace are sent as before. A terminal
+    # without the protocol keeps sending keys as before. Does nothing if
+    # already on.
+    #
+    # Call it after {#enter_alternate_screen}, as each screen has its own stack.
+    #
+    # @return [void]
+    def enable_kitty_keyboard
+      return if @kitty_keyboard
+
+      @buffer << "#{CSI}>#{KITTY_KEYBOARD_FLAGS}u"
+      @kitty_keyboard = true
+      flush
+    end
+
+    # Pop the entry pushed by {#enable_kitty_keyboard} (<tt>CSI < u</tt>),
+    # restoring the terminal's previous keyboard mode, and flush. Does
+    # nothing if it is not on.
+    #
+    # Call it before {#leave_alternate_screen}.
+    #
+    # @return [void]
+    def disable_kitty_keyboard
+      return unless @kitty_keyboard
+
+      @buffer << "#{CSI}<u"
+      @kitty_keyboard = false
+      flush
+    end
+
     # Put the input into raw mode, saving its terminal state for {#disable_raw_mode}.
     #
     # Save the termios state of the SAME fd we are about to raw! — a backtick

data/lib/rubytui/buffer.rb

@@ -97,6 +97,7 @@ module RubyTUI
     # Iterates by grapheme cluster so that combining sequences (Devanagari
     # matras/virama, emoji ZWJ, Latin diacritics) are stored as a single
     # cell symbol.  Wide clusters (2-column) mark the next cell as a spacer.
+    # Control characters (zero width, e.g. a tab or newline) are skipped.
     # Clips at buffer boundaries.
     #
     # @param x [Integer] starting column
@@ -114,6 +115,7 @@ module RubyTUI
         break if col >= @area.right
 
         w = Unicode.cluster_width(gc)
+        next if w.zero?
 
         if col >= @area.x
           idx = index(col, y)
@@ -278,12 +280,12 @@ module RubyTUI
     #   puts buf.to_ansi
     def to_ansi
       csi = "\e["
-      result = String.new(capacity: @area.area * 2)
+      result = String.new(capacity: @area.area * 2, encoding: Encoding::UTF_8)
       prev_style = nil
 
       @area.height.times do |row|
         # Build the row content
-        row_buf = String.new(capacity: @area.width * 2)
+        row_buf = String.new(capacity: @area.width * 2, encoding: Encoding::UTF_8)
         col = 0
         display_col = 0  # track actual terminal column for cursor correction
 

data/lib/rubytui/event.rb

@@ -19,8 +19,8 @@ module RubyTUI
     #   (e.g. {Input::Key::ENTER}, {Input::Key::CHAR})
     # @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})
+    # @param modifiers [Integer] bitmask of {Input::Key::SHIFT}, {Input::Key::ALT},
+    #   {Input::Key::CTRL} and {Input::Key::SUPER} (default: {Input::Key::NONE})
     def initialize(code:, char: nil, modifiers: Input::Key::NONE)
       @code = code
       @char = char
@@ -33,6 +33,8 @@ module RubyTUI
     def alt?   = (@modifiers & Input::Key::ALT) != 0
     # @return [Boolean] true if the {Input::Key::SHIFT} flag is set
     def shift? = (@modifiers & Input::Key::SHIFT) != 0
+    # @return [Boolean] true if the {Input::Key::SUPER} flag (Cmd on macOS) is set
+    def super? = (@modifiers & Input::Key::SUPER) != 0
 
     # Value equality: same code, character and modifiers.
     #
@@ -53,6 +55,7 @@ module RubyTUI
       parts << "Ctrl" if ctrl?
       parts << "Alt" if alt?
       parts << "Shift" if shift?
+      parts << "Super" if super?
       parts << (@char || @code.to_s)
       "KeyEvent(#{parts.join("+")})"
     end

data/lib/rubytui/input/key.rb

@@ -86,6 +86,11 @@ module RubyTUI
       ALT   = 0b010
       # Ctrl modifier bit.
       CTRL  = 0b100
+      # Super modifier bit: Cmd on macOS, the Windows key elsewhere. Reported
+      # only by terminals that send it in a modifier parameter, such as with
+      # the kitty keyboard protocol (see {RubyTUI.run}); xterm sends Meta in
+      # this bit.
+      SUPER = 0b1000
 
       # @!endgroup
     end

data/lib/rubytui/input/parser.rb

@@ -5,13 +5,32 @@ module RubyTUI
     # Decodes raw terminal input into {KeyEvent} and {MouseEvent} objects.
     #
     # Recognised input: printable ASCII, Enter, Tab, Backspace, Ctrl+letter,
+    # Ctrl+Space and Ctrl+\ ] ^ _ (bytes 0 and 28-31),
     # 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),
+    # String), ESC, Alt+key (ESC followed by one character or control byte,
+    # e.g. <tt>ESC DEL</tt> is Alt+Backspace and <tt>ESC ESC</tt> Alt+Escape),
     # 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>),
+    # Back-tab, F1-F12, each with an optional xterm modifier parameter such as
+    # <tt>ESC [ 1 ; 5 A</tt> or <tt>ESC [ 5 ; 5 ~</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.
+    # and SGR and legacy mouse reports (buttons 8-11 give no event).
+    #
+    # Keys sent as <tt>CSI code ; modifiers u</tt> (the kitty keyboard
+    # protocol, see {RubyTUI.run}) or <tt>CSI 27 ; modifiers ; code ~</tt>
+    # (xterm modifyOtherKeys) are recognised whether or not rubytui asked
+    # for them. The key code is a Unicode code point, so the {KeyEvent} is a
+    # character key, or Enter, Tab, Escape or Backspace for codes 13, 9, 27
+    # and 127, or a keypad key reported as the key it stands for (keypad
+    # Enter as Enter, keypad 1 as "1"). The character is the shifted key or
+    # the key's text when the sequence carries one, otherwise the key code
+    # itself, so Ctrl+Shift+A is <tt>char "a"</tt> with Ctrl and Shift
+    # unless the terminal also sends the shifted key "A". Shift+Tab is
+    # {Input::Key::BACKTAB} without Shift. Key releases, modifier and lock
+    # keys pressed on their own, F13 and above, and media keys give no event.
+    #
+    # In every modifier parameter the Shift, Alt, Ctrl and Super (Cmd) bits
+    # are reported; Hyper, Meta, Caps Lock and Num Lock are ignored.
     #
     # String sequences that terminals send as replies are recognised and
     # produce no event: APC (<tt>ESC _</tt>, e.g. Kitty graphics responses),
@@ -19,7 +38,8 @@ module RubyTUI
     # (<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}).
+    # unfinished, or an ESC that does not start ST follows them (see
+    # {#parse_prefix}).
     #
     # The +char+ of every {KeyEvent} it returns is a UTF-8 String.
     #
@@ -37,6 +57,24 @@ module RubyTUI
       STRING_INTRODUCERS = [0x50, 0x58, 0x5D, 0x5E, 0x5F].freeze
       private_constant :STRING_INTRODUCERS
 
+      # Modifier bits reported in a KeyEvent; they match the protocol bits
+      MODIFIER_MASK = Key::SHIFT | Key::ALT | Key::CTRL | Key::SUPER
+      private_constant :MODIFIER_MASK
+
+      # Key codes in CSI u and modifyOtherKeys sequences that are not
+      # characters: C0 keys and the kitty keypad keys (57399-57426), as a key
+      # code Symbol or the character the key types
+      CODE_KEYS = {
+        9 => Key::TAB, 13 => Key::ENTER, 27 => Key::ESCAPE, 127 => Key::BACKSPACE,
+        **(0..9).to_h { |digit| [57399 + digit, digit.to_s] },
+        57409 => ".", 57410 => "/", 57411 => "*", 57412 => "-", 57413 => "+",
+        57414 => Key::ENTER, 57415 => "=", 57416 => ",",
+        57417 => Key::LEFT, 57418 => Key::RIGHT, 57419 => Key::UP, 57420 => Key::DOWN,
+        57421 => Key::PAGE_UP, 57422 => Key::PAGE_DOWN, 57423 => Key::HOME,
+        57424 => Key::END_KEY, 57425 => Key::INSERT, 57426 => Key::DELETE
+      }.freeze
+      private_constant :CODE_KEYS
+
       # Parse raw bytes into an Event.
       #
       # Input in any encoding is decoded byte-wise; a character is returned as
@@ -69,28 +107,30 @@ module RubyTUI
       # 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+.
+      # final byte comes within its first 256 bytes, or a byte that cannot
+      # be part of a CSI sequence comes first, it was typed: 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).
+      # including its ST or BEL terminator and gives no event. Replies hold
+      # no other ESC, so an ESC inside it that does not start ST means it was
+      # typed: 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. 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)
+      #   CSI or 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 CSI or string sequence is taken to be
+      #   typed, so only its introducer is taken, as Alt+[ or Alt+character
+      #   (2 bytes), 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 O</tt> is Alt+O, and a cut-off UTF-8
+      #   character 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
@@ -128,10 +168,11 @@ module RubyTUI
 
       # 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).
+      # CSI or string sequence with its introducer (Alt+[ or 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))
+        return 2 if bytes.getbyte(0) == 0x1B &&
+                    (bytes.getbyte(1) == 0x5B || STRING_INTRODUCERS.include?(bytes.getbyte(1)))
 
         bytes.bytesize
       end
@@ -163,13 +204,13 @@ module RubyTUI
       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+[).
+      # Any other byte, or no final byte within MAX_CSI_BYTES, means it was
+      # typed: 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)
+          return 2 unless b.between?(0x20, 0x3F)
         end
         bytes.bytesize >= MAX_CSI_BYTES ? 2 : nil
       end
@@ -187,8 +228,9 @@ module RubyTUI
         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.
+      # String sequence: ends after BEL or ST (ESC \); nil while neither has
+      # come. Terminal replies hold no other ESC, so an ESC followed by any
+      # other byte means the introducer was typed: 2 (Alt+character).
       def string_length(bytes)
         stop = bytes.index(/[\a\e]/, 2)
         return nil if stop.nil?
@@ -197,7 +239,7 @@ module RubyTUI
         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
+        following == 0x5C ? stop + 2 : 2
       end
 
       # Length of the UTF-8 character starting at +start+; an invalid sequence
@@ -235,10 +277,15 @@ module RubyTUI
           KeyEvent.new(code: Key::BACKSPACE)
         when 8   # BS (backspace on some terminals)
           KeyEvent.new(code: Key::BACKSPACE)
+        when 0   # Ctrl+Space
+          KeyEvent.new(code: Key::CHAR, char: " ", modifiers: Key::CTRL)
         when 1..26
           # Ctrl+A through Ctrl+Z
           char = (ord + 96).chr(Encoding::UTF_8) # Convert to lowercase letter
           KeyEvent.new(code: Key::CHAR, char: char, modifiers: Key::CTRL)
+        when 28..31
+          # Ctrl+\ ] ^ _
+          KeyEvent.new(code: Key::CHAR, char: (ord + 64).chr(Encoding::UTF_8), modifiers: Key::CTRL)
         when 32..126
           # Printable ASCII
           KeyEvent.new(code: Key::CHAR, char: utf8_char(byte))
@@ -254,13 +301,10 @@ module RubyTUI
         # 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)
+        # CSI key sequences: ESC [ params final, params being ;-separated
+        # fields of :-separated numbers
+        when /\A\e\[([\d;:]*)([A-Za-z~])\z/
+          parse_csi_key($1, $2)
         # Normal mouse: ESC [ M Cb Cx Cy (legacy, 3 raw bytes after M)
         when /\A\e\[M(.{3})\z/m
           parse_normal_mouse($1)
@@ -273,16 +317,93 @@ module RubyTUI
           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)
+        # Alt+key: ESC + one (possibly multi-byte) character, control byte
+        # (ESC DEL is Alt+Backspace) or ESC (Alt+Escape)
+        when /\A\e(.+)\z/m
+          key = if $1 == "\e"
+                  KeyEvent.new(code: Key::ESCAPE)
+                elsif !$1.start_with?("\e")
+                  parse($1)
+                end
+          with_modifiers(key, Key::ALT)
         else
           nil
         end
       end
 
-      # CSI single letter: ESC [ X
+      # CSI key sequence. +params+ is the parameter string, +final+ the final
+      # byte. The second field is the modifier parameter, with an optional
+      # event type (1 press, 2 repeat, 3 release) after a colon.
+      def parse_csi_key(params, final)
+        fields = params.split(";", -1).map { |field| field.split(":", -1) }
+        number = fields.dig(0, 0)
+        mod_code, event_type = fields[1]
+        return nil if event_type == "3" # key release
+
+        modifiers = decode_modifiers(mod_code.to_s.empty? ? 1 : mod_code.to_i)
+        case final
+        when "u"
+          parse_csi_u(fields, modifiers)
+        when "~"
+          if number == "27" && fields.size == 3 # xterm modifyOtherKeys
+            parse_key_code(fields[2][0].to_i, modifiers)
+          else
+            with_modifiers(parse_csi_tilde(number.to_i), modifiers)
+          end
+        else
+          # The number is 1, or omitted when there are no modifiers
+          return nil unless [nil, "", "1"].include?(number)
+
+          with_modifiers(parse_csi_letter(final), modifiers)
+        end
+      end
+
+      # CSI u: ESC [ code[:shifted[:base]] ; modifiers ; text u, where text is
+      # :-separated code points. The base layout key is not used.
+      def parse_csi_u(fields, modifiers)
+        code, shifted = fields[0]
+        text = fields[2]&.map { |cp| codepoint_char(cp.to_i) }
+        if text&.all?
+          KeyEvent.new(code: Key::CHAR, char: text.join, modifiers: modifiers)
+        else
+          parse_key_code(code.to_i, modifiers, shifted.to_s.empty? ? nil : shifted.to_i)
+        end
+      end
+
+      # KeyEvent for a key code (and the shifted key, if sent) from a CSI u or
+      # modifyOtherKeys sequence, or nil if it has no key.
+      def parse_key_code(code, modifiers, shifted = nil)
+        if code == 9 && (modifiers & Key::SHIFT) != 0
+          return KeyEvent.new(code: Key::BACKTAB, modifiers: modifiers & ~Key::SHIFT)
+        end
+
+        case (key = CODE_KEYS[code])
+        when Symbol then KeyEvent.new(code: key, modifiers: modifiers)
+        when String then KeyEvent.new(code: Key::CHAR, char: key, modifiers: modifiers)
+        else
+          char = codepoint_char(shifted || code)
+          char && KeyEvent.new(code: Key::CHAR, char: char, modifiers: modifiers)
+        end
+      end
+
+      # +cp+ as a UTF-8 String, or nil if it is not a printable character:
+      # a C0 or C1 control code, DEL, a surrogate, past U+10FFFF, or in the
+      # private use area U+E000-U+F8FF, where the kitty keyboard protocol puts
+      # functional keys.
+      def codepoint_char(cp)
+        return nil if cp < 0x20 || cp.between?(0x7F, 0x9F) || cp.between?(0xD800, 0xDFFF) ||
+                      cp.between?(0xE000, 0xF8FF) || cp > 0x10FFFF
+
+        cp.chr(Encoding::UTF_8)
+      end
+
+      # +event+ with +modifiers+ added, or nil if +event+ is nil
+      def with_modifiers(event, modifiers)
+        event && KeyEvent.new(code: event.code, char: event.char, modifiers: event.modifiers | modifiers)
+      end
+
+      # CSI letter: ESC [ X, or ESC [ 1 ; MOD X. CSI R is a cursor position
+      # report, not F3.
       def parse_csi_letter(letter)
         case letter
         when "A" then KeyEvent.new(code: Key::UP)
@@ -292,17 +413,26 @@ module RubyTUI
         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)
+        when "P" then KeyEvent.new(code: Key::F1)
+        when "Q" then KeyEvent.new(code: Key::F2)
+        when "S" then KeyEvent.new(code: Key::F4)
         else nil
         end
       end
 
-      # CSI tilde sequences: ESC [ N ~
+      # CSI tilde sequences: ESC [ N ~ or ESC [ N ; MOD ~
       def parse_csi_tilde(n)
         case n
+        when 1, 7 then KeyEvent.new(code: Key::HOME)
         when 2  then KeyEvent.new(code: Key::INSERT)
         when 3  then KeyEvent.new(code: Key::DELETE)
+        when 4, 8 then KeyEvent.new(code: Key::END_KEY)
         when 5  then KeyEvent.new(code: Key::PAGE_UP)
         when 6  then KeyEvent.new(code: Key::PAGE_DOWN)
+        when 11 then KeyEvent.new(code: Key::F1)
+        when 12 then KeyEvent.new(code: Key::F2)
+        when 13 then KeyEvent.new(code: Key::F3)
+        when 14 then KeyEvent.new(code: Key::F4)
         when 15 then KeyEvent.new(code: Key::F5)
         when 17 then KeyEvent.new(code: Key::F6)
         when 18 then KeyEvent.new(code: Key::F7)
@@ -315,15 +445,6 @@ module RubyTUI
         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
@@ -337,20 +458,19 @@ module RubyTUI
         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
+      # Decode a modifier parameter: 1 plus a bit field of Shift (1), Alt (2),
+      # Ctrl (4) and Super (8), e.g. 2=Shift, 5=Ctrl, 6=Shift+Ctrl, 9=Super.
+      # Higher bits are dropped; 0 counts as 1 (no modifiers).
       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
+        [code - 1, 0].max & MODIFIER_MASK
       end
 
       # SGR extended mouse mode: ESC [ < Cb ; Cx ; Cy M (press) or m (release)
-      # Cb encodes button + modifiers + motion flag
+      # Cb encodes button + modifiers + motion flag. Buttons 8-11 (Cb 128
+      # and up) give no event.
       def parse_sgr_mouse(cb, cx, cy, terminator)
+        return nil if (cb & 128) != 0
+
         # Coordinates are 1-based in SGR mode
         x = cx - 1
         y = cy - 1
@@ -392,9 +512,12 @@ module RubyTUI
         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)
+      # Legacy normal mouse: ESC [ M Cb Cx Cy (raw bytes, 32-based encoding).
+      # Buttons 8-11 (Cb 128 and up) give no event.
       def parse_normal_mouse(raw)
         cb = raw.getbyte(0) - 32
+        return nil if cb.negative? || (cb & 128) != 0
+
         x = raw.getbyte(1) - 33
         y = raw.getbyte(2) - 33
 

data/lib/rubytui/input/reader.rb

@@ -21,14 +21,12 @@ module RubyTUI
     # String sequences that terminals write as replies (APC such as Kitty
     # graphics responses, OSC, DCS, SOS, PM; see {Parser}) are read and
     # discarded without an event when their terminator (ST or BEL) arrives.
-    # An ESC inside one that does not start ST ends it just before that ESC,
-    # also without an event.
     #
-    # If no byte arrives for {ESC_TIMEOUT_MS}, or the input ends, before
-    # either happens, the sequence was typed, not sent: its introducer is
-    # returned as an Alt key (<tt>ESC P</tt> as Alt+P, likewise Alt+X,
-    # Alt+], Alt+^ and Alt+_) and every byte after it, a final lone ESC
-    # included, is decoded as normal input.
+    # If an ESC that does not start ST comes first, or no byte arrives for
+    # {ESC_TIMEOUT_MS}, or the input ends, the sequence was typed, not sent:
+    # its introducer is returned as an Alt key (<tt>ESC P</tt> as Alt+P,
+    # likewise Alt+X, Alt+], Alt+^ and Alt+_) and every byte after it, a
+    # final lone ESC included, is decoded as normal input.
     #
     # If one reaches 4096 bytes with no terminator while bytes keep
     # arriving, it is taken to be a reply: those bytes are discarded, and so
@@ -38,9 +36,10 @@ module RubyTUI
     # ends; an ESC not yet discarded at that point is decoded as normal
     # input.
     #
-    # A CSI sequence with no final byte in its first 256 bytes is returned as
-    # Alt+[, and the bytes after <tt>ESC [</tt> are decoded as normal input
-    # (see {Parser#parse_prefix}).
+    # A CSI sequence with no final byte in its first 256 bytes, or cut off
+    # by a pause of {ESC_TIMEOUT_MS}, the end of input or a byte that cannot
+    # continue it, was typed: it is returned as Alt+[, and the bytes after
+    # <tt>ESC [</tt> are decoded as normal input (see {Parser#parse_prefix}).
     #
     # When the input is a TTY that reports its size (+winsize+), {#poll}
     # also returns a {ResizeEvent} after the terminal size changes.

data/lib/rubytui/version.rb

@@ -2,5 +2,5 @@
 
 module RubyTUI
   # Gem version string.
-  VERSION = "1.2.6"
+  VERSION = "1.2.7"
 end

data/lib/rubytui/widgets/async_image.rb

@@ -208,9 +208,11 @@ module RubyTUI
 
         return if render_area.empty?
 
-        case @state
+        # Read the state and image together, as the loading thread sets both
+        state, image_widget = @mutex.synchronize { [@state, @image_widget] }
+        case state
         when STATE_READY
-          @image_widget&.render(render_area, buf)
+          image_widget&.render(render_area, buf)
         when STATE_LOADING
           render_placeholder(render_area, buf, @placeholder || "Loading...")
         when STATE_ERROR

data/lib/rubytui/widgets/block.rb

@@ -238,6 +238,7 @@ module RubyTUI
         end
       end
 
+      # A new frozen [top, right, bottom, left] Array, never the caller's
       def normalize_padding(padding)
         case padding
         when nil
@@ -248,12 +249,12 @@ module RubyTUI
           case padding.length
           when 1 then [padding[0]] * 4
           when 2 then [padding[0], padding[1], padding[0], padding[1]]
-          when 4 then padding
+          when 4 then padding.dup
           else [0, 0, 0, 0]
           end
         else
           [0, 0, 0, 0]
-        end
+        end.freeze
       end
     end
   end

data/lib/rubytui/widgets/canvas.rb

@@ -40,10 +40,12 @@ module RubyTUI
 
       # @param x_bounds [Array(Numeric, Numeric), nil] <tt>[min, max]</tt> data range
       #   mapped to the canvas width (default: nil, computed from the x coordinates
-      #   of points and lines)
+      #   of points and lines). For given or computed bounds, an equal min and max
+      #   are widened to <tt>max = min + 1</tt>
       # @param y_bounds [Array(Numeric, Numeric), nil] <tt>[min, max]</tt> data range
       #   mapped to the canvas height, max at the top (default: nil, computed from
-      #   the y coordinates of points and lines)
+      #   the y coordinates of points and lines; equal bounds are widened as for
+      #   +x_bounds+)
       # @param style [Style] style for labels added without a style (default: {Style::DEFAULT})
       # @param marker_style [Style, nil] style for dots drawn without a style
       #   (default: white foreground)
@@ -186,7 +188,10 @@ module RubyTUI
       # axis: 0 for x, 1 for y (index into points and into each line's endpoints)
       def compute_bounds(bounds, canvas_size, axis)
         if bounds
-          [bounds[0].to_f, bounds[1].to_f]
+          mn = bounds[0].to_f
+          mx = bounds[1].to_f
+          mx = mn + 1 if mx == mn
+          [mn, mx]
         else
           coords = @points.map { |p| p[axis] } + @lines.flat_map { |l| [l[axis], l[axis + 2]] }
           return [0.0, canvas_size.to_f] if coords.empty?

data/lib/rubytui/widgets/chart.rb

@@ -29,19 +29,27 @@ module RubyTUI
       # @param datasets [Array<Dataset>] series to plot; datasets with fewer than
       #   2 points are skipped (default: [])
       # @param x_axis [Array(String, Numeric, Numeric), nil] <tt>[label, min, max]</tt>;
-      #   +min+/+max+ may be nil for bounds computed from the data. The bottom row of
+      #   +min+ and +max+ may each be nil for a bound computed from the data (see
+      #   below). The bottom row of
       #   the area is always reserved for the x axis line and its min/max values;
       #   when set, the label is also drawn centered on it, over the values. The
       #   label and min value are truncated to the plot width (whole grapheme
-      #   clusters), and the max value is omitted when it would overlap the min
-      #   value (default: nil, bounds computed from the data and no label)
+      #   clusters), and the max value is omitted unless at least one column
+      #   separates it from the min value (default: nil, bounds computed from
+      #   the data and no label)
       # @param y_axis [Array(String, Numeric, Numeric), nil] <tt>[label, min, max]</tt>;
-      #   +min+/+max+ may be nil for bounds computed from the data. When set, the
-      #   min/max values are drawn left of a vertical axis line and the label's first
-      #   character at mid-height. The label column is as wide as the wider of the
-      #   min/max values drawn, i.e. of the final bounds (computed bounds with equal
-      #   min and max are widened to <tt>max = min + 1</tt>) (default: nil, no y
-      #   axis; bounds computed from the data)
+      #   +min+ and +max+ may each be nil for a bound computed from the data. When
+      #   set, the min/max values are drawn left of a vertical axis line and the
+      #   label's first grapheme cluster at mid-height, if it fits the label
+      #   column. A plot (the area minus the x axis row) 1 row tall shows only
+      #   the max value, and the label is drawn only when the plot is at least
+      #   3 rows tall. The label column is as wide as the wider of the min/max values
+      #   drawn, i.e. of the final bounds (default: nil, no y axis; bounds
+      #   computed from the data).
+      #
+      #   For both axes, bounds with equal min and max are widened to
+      #   <tt>max = min + 1</tt>, and a bound computed from the data that would
+      #   reach or pass the explicit other bound is set 1 beyond it.
       # @param style [Style, nil] base style of the area inside +block+: when it is
       #   not {Style::DEFAULT} it is patched onto every cell, and the axis lines,
       #   labels and plotted dots are drawn with this style patched ({Style#patch})
@@ -143,32 +151,29 @@ module RubyTUI
         [format_num(y_min).length, format_num(y_max).length].max
       end
 
-      def compute_x_bounds
-        if @x_axis
-          _, mn, mx = @x_axis
-          return [mn, mx] if mn && mx
-        end
-
-        all_x = @datasets.flat_map { |ds| ds.data.map { |x, _| x } }
-        return [0.0, 1.0] if all_x.empty?
-
-        mn = all_x.min.to_f
-        mx = all_x.max.to_f
-        mx = mn + 1 if mx == mn
-        [mn, mx]
-      end
-
-      def compute_y_bounds
-        if @y_axis
-          _, mn, mx = @y_axis
-          return [mn, mx] if mn && mx
+      def compute_x_bounds = compute_bounds(@x_axis, 0)
+      def compute_y_bounds = compute_bounds(@y_axis, 1)
+
+      # [min, max] for an axis (<tt>[label, min, max]</tt> or nil): each
+      # explicit bound where set, otherwise the data's along coordinate
+      # +index+ (0 x, 1 y). Equal bounds are widened to max = min + 1; a
+      # computed bound that reaches or passes the explicit one is set 1
+      # beyond it.
+      def compute_bounds(axis, index)
+        _, mn, mx = axis
+        values = @datasets.flat_map { |ds| ds.data.map { |point| point[index] } }
+        if mn.nil? && mx.nil?
+          return [0.0, 1.0] if values.empty?
+
+          mn = values.min.to_f
+          mx = values.max.to_f
+        elsif mn.nil?
+          mn = values.min&.to_f || mx - 1
+          mn = mx - 1 if mn >= mx
+        elsif mx.nil?
+          mx = values.max&.to_f || mn + 1
+          mx = mn + 1 if mx <= mn
         end
-
-        all_y = @datasets.flat_map { |ds| ds.data.map { |_, y| y } }
-        return [0.0, 1.0] if all_y.empty?
-
-        mn = all_y.min.to_f
-        mx = all_y.max.to_f
         mx = mn + 1 if mx == mn
         [mn, mx]
       end
@@ -183,15 +188,19 @@ module RubyTUI
           buf[chart_area.x - 1, y]&.set("\u2502", @axis_style) if chart_area.x > render_area.x
         end
 
-        # Y labels at top and bottom
+        # Y labels at top and bottom; a 1-row plot has room for the max only
         y_label_x = render_area.x
         buf.set_string(y_label_x, chart_area.y, format_num(y_max), @label_style)
-        buf.set_string(y_label_x, chart_area.bottom - 1, format_num(y_min), @label_style)
+        if chart_area.height > 1
+          buf.set_string(y_label_x, chart_area.bottom - 1, format_num(y_min), @label_style)
+        end
 
-        # Y axis label (vertically centered, first char)
-        if label && !label.empty?
+        # Y axis label (vertically centered): its first grapheme cluster, if it
+        # fits the label column and the plot has a row between the values
+        if label && !label.empty? && chart_area.height > 2
           mid_y = chart_area.y + chart_area.height / 2
-          buf.set_string(render_area.x, mid_y, label[0], @label_style)
+          first = Unicode.truncate_to_width(label.grapheme_clusters.first, chart_area.x - 1 - render_area.x)
+          buf.set_string(render_area.x, mid_y, first, @label_style)
         end
       end
 
@@ -209,12 +218,12 @@ module RubyTUI
         end
 
         # X labels at left and right, truncated to the plot width; the max label
-        # is omitted when it would overlap the min label
+        # is omitted unless at least one column separates it from the min label
         min_str = Unicode.truncate_to_width(format_num(x_min), chart_area.width)
         max_str = format_num(x_max)
         buf.set_string(chart_area.x, x_axis_y, min_str, @label_style)
         max_x = chart_area.right - Unicode.string_width(max_str)
-        if max_x >= chart_area.x + Unicode.string_width(min_str)
+        if max_x > chart_area.x + Unicode.string_width(min_str)
           buf.set_string(max_x, x_axis_y, max_str, @label_style)
         end
 

data/lib/rubytui/widgets/gauge.rb

@@ -120,17 +120,20 @@ module RubyTUI
           # On empty portion: gauge color as fg, default bg
           empty_label_style = @label_style || Style.new.fg(gauge_fg).bold
 
+          # One cell per grapheme cluster; control characters are skipped
           cx = label_x
-          label_text.each_char do |ch|
-            ch_w = Unicode.char_width(ch)
+          label_text.grapheme_clusters.each do |gc|
+            gc_w = Unicode.cluster_width(gc)
+            next if gc_w.zero?
+
             col_offset = cx - render_area.x
             char_style = col_offset < boundary ? filled_label_style : empty_label_style
-            buf[cx, label_y]&.set(ch, char_style)
-            # Mark spacer for wide chars
-            if ch_w == 2 && cx + 1 < render_area.right
+            buf[cx, label_y]&.set(gc, char_style)
+            # Mark spacer for wide clusters
+            if gc_w == 2 && cx + 1 < render_area.right
               buf[cx + 1, label_y]&.set("", char_style)
             end
-            cx += ch_w
+            cx += gc_w
           end
         end
       end

data/lib/rubytui/widgets/input_field.rb

@@ -26,48 +26,66 @@ module RubyTUI
 
       # Insert a character at the cursor position
       #
+      # A cursor past the end (or before the start) of the text is first moved
+      # to the end (or start).
+      #
       # @param char [String] character (or string) to insert; the cursor advances by its length
       # @return [void]
       def insert(char)
+        @cursor = @cursor.clamp(0, @text.length)
         @text.insert(@cursor, char)
         @cursor += char.length
       end
 
-      # Delete character before cursor (backspace)
+      # Delete the grapheme cluster before the cursor (backspace)
       #
-      # Does nothing when the cursor is at the start.
+      # A letter with its combining marks, or an emoji sequence, is deleted as
+      # a whole, as is a cluster the cursor is inside; the cursor moves to the
+      # cluster's start. Does nothing when the cursor is at the start. A cursor
+      # past the end of the text moves back one position.
       #
       # @return [void]
       def backspace
-        return if @cursor == 0
+        return if @cursor <= 0
+        return @cursor -= 1 if @cursor > @text.length
 
-        @text.slice!(@cursor - 1)
-        @cursor -= 1
+        range = cluster_at(@cursor - 1)
+        @text.slice!(range)
+        @cursor = range.begin
       end
 
-      # Delete character at cursor (delete key)
+      # Delete the grapheme cluster at the cursor (delete key)
       #
+      # The whole cluster is deleted; a cursor inside it moves to its start.
       # Does nothing when the cursor is at the end.
       #
       # @return [void]
       def delete
-        return if @cursor >= @text.length
+        return if @cursor >= @text.length || @cursor.negative?
 
-        @text.slice!(@cursor)
+        range = cluster_at(@cursor)
+        @text.slice!(range)
+        @cursor = range.begin
       end
 
-      # Move cursor left
+      # Move cursor left, to the start of the previous grapheme cluster
       #
       # @return [void]
       def move_left
-        @cursor = [@cursor - 1, 0].max
+        @cursor = if @cursor <= 0 then 0
+                  elsif @cursor > @text.length then @cursor - 1
+                  else cluster_at(@cursor - 1).begin
+                  end
       end
 
-      # Move cursor right
+      # Move cursor right, past the grapheme cluster at the cursor
       #
       # @return [void]
       def move_right
-        @cursor = [@cursor + 1, @text.length].min
+        @cursor = if @cursor >= @text.length then @text.length
+                  elsif @cursor.negative? then 0
+                  else cluster_at(@cursor).end
+                  end
       end
 
       # Move cursor to start
@@ -131,10 +149,11 @@ module RubyTUI
 
       # Handle a key event, returns true if the event was consumed
       #
-      # Character keys without Ctrl insert <tt>event.char</tt>. Backspace, Delete,
+      # Character keys without Ctrl or Super insert <tt>event.char</tt>. Backspace, Delete,
       # Left, Right, Home and End edit or move. Ctrl-A / Ctrl-E move to start / end,
       # Ctrl-K / Ctrl-U delete to end / start, Ctrl-W deletes the previous word.
-      # Other Ctrl combinations, other keys and non-{KeyEvent} events are not consumed.
+      # Other Ctrl combinations, Super (Cmd) combinations, other keys and
+      # non-{KeyEvent} events are not consumed.
       #
       # @param event [Event] the input event
       # @return [Boolean] true if the event was consumed
@@ -152,6 +171,8 @@ module RubyTUI
             when "w" then delete_word_back; true
             else false
             end
+          elsif event.super?
+            false
           else
             insert(event.char) if event.char
             true
@@ -166,6 +187,20 @@ module RubyTUI
           false
         end
       end
+
+      private
+
+      # Character range of the grapheme cluster that contains character
+      # +index+ (0 <= index < text length)
+      def cluster_at(index)
+        start = 0
+        @text.grapheme_clusters.each do |gc|
+          stop = start + gc.length
+          return start...stop if index < stop
+
+          start = stop
+        end
+      end
     end
 
     # InputField renders a single-line text input with cursor.

data/lib/rubytui/widgets/paragraph.rb

@@ -26,10 +26,11 @@ module RubyTUI
       #   into lines on newlines, a Span is split the same way into one-span Lines
       #   that keep its {Span#style}, +nil+ means no text, other objects are
       #   converted with +to_s+ (default: nil)
-      # @param style [Style] base style of the text. Each span is drawn with this
+      # @param style [Style, nil] base style of the text. Each span is drawn with this
       #   style patched ({Style#patch}) with {Text#style}, then {Line#style}, then
       #   {Span#style}, so later layers win. When it is not {Style::DEFAULT} it is
-      #   also patched onto every cell of the area (default: {Style::DEFAULT})
+      #   also patched onto every cell of the area. +nil+ is treated as
+      #   {Style::DEFAULT} (default: {Style::DEFAULT})
       # @param alignment [Symbol] +:left+ (default), +:center+ or +:right+
       # @param wrap [Symbol] {WRAP_WORD} (default), {WRAP_CHAR} or {WRAP_NONE}. Wrapped
       #   lines take the style of the original line's first span and keep the
@@ -43,7 +44,7 @@ module RubyTUI
         block: nil  # optional Block to render inside
       )
         @text = normalize_text(text)
-        @style = style
+        @style = style || Style::DEFAULT
         @alignment = alignment
         @wrap = wrap
         @block = block
@@ -137,7 +138,7 @@ module RubyTUI
 
         words = plain.split(/(\s+)/)
         wrapped = []
-        current = String.new
+        current = String.new(encoding: plain.encoding)
         current_width = 0
 
         words.each do |word|
@@ -165,7 +166,7 @@ module RubyTUI
         line_style = line.spans.first&.style || Style::DEFAULT
 
         wrapped = []
-        current = String.new
+        current = String.new(encoding: plain.encoding)
         current_width = 0
 
         # Break only between grapheme clusters, so conjuncts and ZWJ sequences stay whole
@@ -173,7 +174,7 @@ module RubyTUI
           gc_width = Unicode.cluster_width(gc)
           if current_width + gc_width > max_width
             wrapped << Line.new([Span.new(current, line_style)], line.style) unless current.empty?
-            current = String.new
+            current = String.new(encoding: plain.encoding)
             current_width = 0
           end
           current << gc

data/lib/rubytui.rb

@@ -104,10 +104,13 @@ module RubyTUI
     # @param input [IO] input stream (default: $stdin)
     # @param mouse [Boolean] enable mouse event reporting (default: false)
     # @param alternate_screen [Boolean] enter alternate screen buffer (default: true)
+    # @param kitty_keyboard [Boolean] turn on the kitty keyboard protocol
+    #   (see {.run}) (default: false)
     # @return [Array(Terminal, Input::Reader)] terminal and reader pair
     # @see .run
     # @see .restore
-    def init(output: $stdout, input: $stdin, mouse: false, alternate_screen: true)
+    def init(output: $stdout, input: $stdin, mouse: false, alternate_screen: true,
+             kitty_keyboard: false)
       backend = AnsiBackend.new(output: output, input: input)
       terminal = Terminal.new(backend: backend)
       reader = Input::Reader.new(input: input)
@@ -115,6 +118,7 @@ module RubyTUI
       backend.enable_raw_mode
       backend.hide_cursor
       terminal.enter_alternate_screen if alternate_screen
+      backend.enable_kitty_keyboard if kitty_keyboard
       backend.enable_mouse if mouse
       backend.flush
 
@@ -123,7 +127,8 @@ module RubyTUI
 
     # Restore terminal to normal state.
     #
-    # Disables mouse, shows cursor, leaves alternate screen, and disables raw mode.
+    # Disables mouse, shows cursor, turns off the kitty keyboard protocol if
+    # {.init} turned it on, leaves alternate screen, and disables raw mode.
     #
     # @param terminal [Terminal] the terminal to restore
     # @param alternate_screen [Boolean] whether alternate screen was used (must match {.init})
@@ -132,6 +137,7 @@ module RubyTUI
     def restore(terminal, alternate_screen: true)
       terminal.backend.disable_mouse
       terminal.backend.show_cursor
+      terminal.backend.disable_kitty_keyboard
       terminal.leave_alternate_screen if alternate_screen
       terminal.backend.disable_raw_mode
       terminal.backend.flush
@@ -147,6 +153,19 @@ module RubyTUI
     # @param mouse [Boolean] enable mouse event reporting (default: false)
     # @param alternate_screen [Boolean] use alternate screen buffer (default: true).
     #   Set to +false+ to keep output in terminal scrollback after exit.
+    # @param kitty_keyboard [Boolean] ask the terminal to report keys with the
+    #   kitty keyboard protocol (default: false). On terminals that support it
+    #   (kitty, Ghostty, iTerm2, Alacritty, foot; WezTerm with its
+    #   +enable_kitty_keyboard+ setting), Ctrl+Shift+letter,
+    #   Ctrl or Alt with digits and punctuation, and Super (Cmd) combinations
+    #   that the terminal passes on are reported, and Ctrl+I, Ctrl+M, Ctrl+H
+    #   and Ctrl+[ arrive as Ctrl+letter instead of Tab, Enter, Backspace and
+    #   Escape. The Escape key arrives as a sequence of its own, without the
+    #   wait that separates a lone ESC byte from an escape sequence. Plain and
+    #   Shift-ed text, Enter, Tab and Backspace are unchanged, as are all keys
+    #   on terminals without the protocol (such as macOS Terminal). The mode
+    #   is turned off again when the block exits or raises.
+    #   See {AnsiBackend#enable_kitty_keyboard}.
     # @yield [terminal, reader] the initialized terminal and input reader
     # @yieldparam terminal [Terminal]
     # @yieldparam reader [Input::Reader]
@@ -165,9 +184,11 @@ module RubyTUI
     #   RubyTUI.run(alternate_screen: false) do |terminal, reader|
     #     terminal.draw { |frame| frame.buffer.set_string(0, 0, "Stays visible") }
     #   end
-    def run(output: $stdout, input: $stdin, mouse: false, alternate_screen: true)
+    def run(output: $stdout, input: $stdin, mouse: false, alternate_screen: true,
+            kitty_keyboard: false)
       terminal, reader = init(output: output, input: input, mouse: mouse,
-                              alternate_screen: alternate_screen)
+                              alternate_screen: alternate_screen,
+                              kitty_keyboard: kitty_keyboard)
       yield terminal, reader
     ensure
       restore(terminal, alternate_screen: alternate_screen) if terminal

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubytui
 version: !ruby/object:Gem::Version
-  version: 1.2.6
+  version: 1.2.7
 platform: ruby
 authors:
 - CoCL
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Zero-dependency terminal user interface library
 test_files: []