tuile 0.3.0 → 0.4.0

data/lib/tuile/component.rb

@@ -4,8 +4,10 @@ module Tuile
   # A UI component which is positioned on the screen and draws characters into
   # its bounding rectangle (in {#repaint}).
   #
-  # Component is considered invisible if {#rect} is empty or one of left/top is
-  # negative. The component won't draw when invisible.
+  # Painting is gated by attachment: a detached component (one whose {#root}
+  # isn't {Screen#pane}) is never enqueued for repaint via {#invalidate}, and
+  # any stale invalidation entries are filtered out at drain time. Subclasses
+  # can paint freely in {#repaint} without re-asserting attachment.
   class Component
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
@@ -66,9 +68,11 @@ module Tuile
     # responsibility for {#rect}. Everything else should call super.
     #
     # A component must not draw outside of {#rect}.
+    #
+    # Only called when the component is attached.
     # @return [void]
     def repaint
-      return if rect.empty? || rect.left.negative? || rect.top.negative?
+      return if rect.empty?
       return if children.any? && children_tile_rect?
 
       clear_background
@@ -251,8 +255,16 @@ module Tuile
 
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
+    #
+    # No-op when the component is not {#attached?} — a detached component has
+    # no place on the screen to paint to, so {Screen} must never end up
+    # repainting it. Callers don't need to guard their own `invalidate` calls;
+    # mutating a detached component (e.g. setting `lines=` on a {List} sitting
+    # inside a closed {Component::Popup}) is silent.
     # @return [void]
     def invalidate
+      return unless attached?
+
       screen.invalidate(self)
     end
 

data/lib/tuile/keys.rb

@@ -42,19 +42,71 @@ module Tuile
     # @return [String]
     PAGE_DOWN = "\e[6~"
     # @return [String]
-    BACKSPACE = ""
+    BACKSPACE = "\x7f"
     # @return [String]
     DELETE = "\e[3~"
+
+    # Ctrl+letter sends bytes 0x01..0x1a. Note that {CTRL_H} == `"\b"`,
+    # {CTRL_I} == {TAB}, {CTRL_J} == `"\n"`, and {CTRL_M} == {ENTER} —
+    # terminals deliver these key combinations indistinguishably from the
+    # corresponding named keys.
+    # @return [String]
+    CTRL_A = "\x01"
+    # @return [String]
+    CTRL_B = "\x02"
+    # @return [String]
+    CTRL_C = "\x03"
+    # @return [String]
+    CTRL_D = "\x04"
+    # @return [String]
+    CTRL_E = "\x05"
+    # @return [String]
+    CTRL_F = "\x06"
+    # @return [String]
+    CTRL_G = "\x07"
     # @return [String]
     CTRL_H = "\b"
-    # @return [Array<String>]
-    BACKSPACES = [BACKSPACE, CTRL_H].freeze
     # @return [String]
-    CTRL_U = ""
+    CTRL_I = "\t"
+    # @return [String]
+    CTRL_J = "\n"
+    # @return [String]
+    CTRL_K = "\x0b"
+    # @return [String]
+    CTRL_L = "\x0c"
+    # @return [String]
+    CTRL_M = "\r"
+    # @return [String]
+    CTRL_N = "\x0e"
+    # @return [String]
+    CTRL_O = "\x0f"
+    # @return [String]
+    CTRL_P = "\x10"
     # @return [String]
-    CTRL_D = ""
+    CTRL_Q = "\x11"
     # @return [String]
-    ENTER = "
+    CTRL_R = "\x12"
+    # @return [String]
+    CTRL_S = "\x13"
+    # @return [String]
+    CTRL_T = "\x14"
+    # @return [String]
+    CTRL_U = "\x15"
+    # @return [String]
+    CTRL_V = "\x16"
+    # @return [String]
+    CTRL_W = "\x17"
+    # @return [String]
+    CTRL_X = "\x18"
+    # @return [String]
+    CTRL_Y = "\x19"
+    # @return [String]
+    CTRL_Z = "\x1a"
+
+    # @return [Array<String>]
+    BACKSPACES = [BACKSPACE, CTRL_H].freeze
+    # @return [String]
+    ENTER = "\r"
     # @return [String]
     TAB = "\t"
     # The terminal sequence emitted by Shift+Tab in xterm-style terminals
@@ -62,6 +114,22 @@ module Tuile
     # @return [String]
     SHIFT_TAB = "\e[Z"
 
+    # True iff `key` is a single printable character — a one-character string
+    # whose codepoint is not in Unicode's C (Other) category. Rejects multi-
+    # character escape sequences ({UP_ARROW}, mouse events, …), control bytes
+    # ({TAB}, {ENTER}, {ESC}, {CTRL_A}..{CTRL_Z}, {BACKSPACE}), and the empty
+    # string; accepts ASCII letters/digits/punctuation/space *and* non-ASCII
+    # printables like "é".
+    #
+    # Used by {Screen#register_global_shortcut} to reject keys that would
+    # collide with typing, and by {Tuile::Component::TextField} to decide
+    # whether to insert a key at the caret.
+    # @param key [String]
+    # @return [Boolean]
+    def self.printable?(key)
+      key.length == 1 && !key.match?(/\p{C}/)
+    end
+
     # Grabs a key from stdin and returns it. Blocks until the key is obtained.
     # Reads a full ESC key sequence; see constants above for some values returned
     # by this function.
@@ -72,11 +140,26 @@ module Tuile
 
       # Escape sequence. Try to read more data.
       begin
-        # Read 6 chars: mouse events are e.g. `\e[Mxyz`
-        char += $stdin.read_nonblock(6)
+        # Read up to 5 bytes: that's the maximum tail length of any escape
+        # sequence Tuile recognizes after the initial \e (X10 mouse `[Mbxy`,
+        # CTRL+arrow `[1;5D`, etc.). Reading 6 here would over-read into the
+        # next sequence on tight mouse-event bursts — we'd silently steal
+        # the next event's leading \e and the rest of it would surface as
+        # individual printable keypresses in focused inputs.
+        char += $stdin.read_nonblock(5)
       rescue IO::EAGAINWaitReadable
         # The "ESC" key pressed => only the \e char is emitted.
+        return char
+      end
+
+      # If `read_nonblock` returned a partial X10 mouse-report prefix (the
+      # sequence is fixed-length: 3 bytes after `\e[M`), drain the remainder
+      # with a blocking read so the parser downstream sees a complete event
+      # instead of leaking tail bytes as keypresses.
+      if char.start_with?("\e[M") && char.bytesize < 6
+        char += $stdin.read(6 - char.bytesize)
       end
+
       char
     end
   end

data/lib/tuile/mouse_event.rb

@@ -5,7 +5,7 @@ module Tuile
   #
   # @!attribute [r] button
   #   @return [Symbol, nil] one of `:left`, `:middle`, `:right`, `:scroll_up`,
-  #     `:scroll_down`; `nil` if not known.
+  #     `:scroll_down`, `:scroll_left`, `:scroll_right`; `nil` if not known.
   # @!attribute [r] x
   #   @return [Integer] x coordinate, 0-based.
   # @!attribute [r] y
@@ -14,17 +14,34 @@ module Tuile
     # @return [Point] the event's position.
     def point = Point.new(x, y)
 
-    # Checks whether given key is a mouse event key
+    # Checks whether given key is a mouse event key. Returns true on the X10
+    # `\e[M` prefix regardless of length — {.parse} is the place that
+    # validates the full 6-byte shape and raises on malformed input.
     # @param key [String] key read via {Keys.getkey}
     # @return [Boolean] true if it is a mouse event
     def self.mouse_event?(key)
-      key.start_with?("\e[M") && key.size >= 6
+      key.start_with?("\e[M")
     end
 
+    # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y).
+    #
+    # Raises {Tuile::Error} when `key` starts with the mouse prefix but is
+    # not exactly 6 bytes long. Both shorter and longer inputs are bugs in
+    # the upstream key-reader: a shorter prefix means the tail was lost on
+    # the way in, and a longer one means we over-consumed into the next
+    # escape sequence. We refuse to silently truncate either case because
+    # the trailing `\e` of an over-read corrupts the *next* getkey, and the
+    # corruption then surfaces as garbled keystrokes in focused inputs
+    # rather than as a parser failure pointing at the actual cause.
     # @param key [String] key read via {Keys.getkey}
-    # @return [MouseEvent, nil]
+    # @return [MouseEvent, nil] `nil` if `key` is not a mouse event
+    # @raise [Tuile::Error] if `key` is a malformed mouse event
     def self.parse(key)
       return nil unless mouse_event?(key)
+      unless key.bytesize == 6
+        raise Tuile::Error,
+              "malformed mouse event: expected 6 bytes after \\e[M prefix, got #{key.bytesize}: #{key.inspect}"
+      end
 
       button = key[3].ord - 32
       # XTerm reports coordinates 1-based (column N is encoded as N + 32);
@@ -37,6 +54,8 @@ module Tuile
                when 1 then :middle
                when 64 then :scroll_up
                when 65 then :scroll_down
+               when 66 then :scroll_left
+               when 67 then :scroll_right
                end
       MouseEvent.new(button, x, y)
     end

data/lib/tuile/screen.rb

@@ -39,8 +39,17 @@ module Tuile
       # stack and status bar.
       @pane = ScreenPane.new
       @on_error = ->(e) { raise e }
+      # App-level keyboard shortcuts dispatched by {#handle_key} before keys
+      # reach the pane. See {#register_global_shortcut}.
+      @global_shortcuts = {}
     end
 
+    # Entry in the global shortcut registry: the block to run, whether it
+    # pre-empts open popups, and an optional preformatted status-bar hint.
+    # @api private
+    Shortcut = Data.define(:block, :over_popups, :hint)
+    private_constant :Shortcut
+
     # @return [ScreenPane] the structural root of the component tree.
     attr_reader :pane
 
@@ -148,15 +157,45 @@ module Tuile
         @pane.on_tree { it.active = active.include?(it) }
         @focused.on_focus
       end
-      # Popups own their own "q Close" prefix in #keyboard_hint; for the tiled
-      # case Screen tacks on the global "q quit" instead.
+      refresh_status_bar
+    end
+
+    # Rebuild the status-bar text from the current focus and global-shortcut
+    # registry. Called from {#focused=} and whenever the global registry
+    # changes. Popups own their own "q Close" prefix in `#keyboard_hint`;
+    # for the tiled case Screen tacks on the global "q quit" instead.
+    # Global-shortcut hints get spliced in too — see {#global_shortcut_hints}
+    # for the over_popups filter rule.
+    # @api private
+    # @return [void]
+    def refresh_status_bar
       top_popup = @pane.popups.last
+      globals = global_shortcut_hints(popup_open: !top_popup.nil?)
       @pane.status_bar.text = if top_popup.nil?
-                                "q #{Rainbow("quit").cadetblue}  #{active_window&.keyboard_hint}".strip
+                                ["q #{Rainbow("quit").cadetblue}", *globals,
+                                 active_window&.keyboard_hint].compact.reject(&:empty?).join("  ")
                               else
-                                top_popup.keyboard_hint
+                                [*globals, top_popup.keyboard_hint].reject(&:empty?).join("  ")
                               end
     end
+    private :refresh_status_bar
+
+    # Status-bar hints from currently-registered global shortcuts.
+    # When a popup is open, only `over_popups: true` shortcuts contribute —
+    # the rest don't fire in that context, so showing them would be a lie.
+    # Insertion order is preserved (Hash iteration order).
+    # @api private
+    # @param popup_open [Boolean]
+    # @return [Array<String>]
+    def global_shortcut_hints(popup_open:)
+      @global_shortcuts.each_value.filter_map do |s|
+        next if s.hint.nil? || s.hint.empty?
+        next if popup_open && !s.over_popups
+
+        s.hint
+      end
+    end
+    private :global_shortcut_hints
 
     # Internal — use {Component::Popup#open} instead. Adds the popup to
     # {#pane}, centers and focuses it.
@@ -172,16 +211,24 @@ module Tuile
 
     # Runs event loop – waits for keys and sends them to active window. The
     # function exits when the 'ESC' or 'q' key is pressed.
+    #
+    # @param capture_mouse [Boolean] when true (default), enables xterm mouse
+    #   tracking so clicks and scroll wheel arrive as {MouseEvent}s and feed
+    #   {Component#handle_mouse}. When false, no tracking escape sequence is
+    #   written: the terminal keeps its native click handling, which is what
+    #   you want if the app benefits more from select-to-copy than from
+    #   click-to-focus. Components' `handle_mouse` is simply never invoked
+    #   from the loop in that mode (the terminal stops sending the bytes).
     # @return [void]
-    def run_event_loop
+    def run_event_loop(capture_mouse: true)
       @pretend_ui_lock = false
       $stdin.echo = false
-      print MouseEvent.start_tracking
+      print MouseEvent.start_tracking if capture_mouse
       $stdin.raw do
         event_loop
       end
     ensure
-      print MouseEvent.stop_tracking
+      print MouseEvent.stop_tracking if capture_mouse
       print TTY::Cursor.show
       $stdin.echo = true
     end
@@ -197,6 +244,80 @@ module Tuile
     # @return [Boolean] true if focus moved.
     def focus_previous = cycle_focus(forward: false)
 
+    # Registers an app-level keyboard shortcut. When `key` arrives, the block
+    # is invoked on the event-loop thread (so it may freely mutate UI) before
+    # the key reaches any component. Re-registering the same key replaces the
+    # previous binding; use {#unregister_global_shortcut} to remove one.
+    #
+    # Only unprintable keys are accepted — control characters (Ctrl+letter,
+    # ESC, BACKSPACE, ENTER, …) and multi-character escape sequences (arrows,
+    # F-keys, …). Printable keys raise {ArgumentError}: they'd hijack typing
+    # into a {Component::TextField} and should be expressed as
+    # {Component#key_shortcut} instead, which the dispatcher suppresses while
+    # a text widget owns the hardware cursor. TAB and SHIFT_TAB are also
+    # rejected because {#handle_key} intercepts them for focus navigation
+    # before the global registry is consulted, so a binding on them would
+    # silently never fire.
+    #
+    # Pass `hint:` to surface the shortcut in the status bar. It's a
+    # preformatted string the caller fully owns (so colors and the key label
+    # style stay consistent with whatever the host app uses elsewhere). The
+    # framework splices it in like any other status hint: in the tiled case,
+    # right after `q quit` and before the active window's own hint; while a
+    # popup is open, only hints from `over_popups: true` shortcuts are
+    # shown, and they're prepended before the popup's `q Close`.
+    #
+    # Example — open a log popup with Ctrl+L from anywhere, even while a
+    # popup is already on screen:
+    #
+    #   screen.register_global_shortcut(Keys::CTRL_L,
+    #                                   over_popups: true,
+    #                                   hint: "^L #{Rainbow("log").cadetblue}") do
+    #     log_popup.open
+    #   end
+    #
+    # @param key [String] unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC},
+    #   {Keys::PAGE_UP}).
+    # @param over_popups [Boolean] when true, fires even while a modal popup
+    #   is open (pre-empting the popup's own key handling). When false
+    #   (default), the shortcut is suppressed while any popup is open and
+    #   the popup gets the key instead.
+    # @param hint [String, nil] preformatted status-bar hint (e.g.
+    #   `"^L #{Rainbow("log").cadetblue}"`). When nil (default) the shortcut
+    #   is silent in the status bar.
+    # @yield invoked with no arguments when `key` is pressed.
+    # @return [void]
+    def register_global_shortcut(key, over_popups: false, hint: nil, &block)
+      raise ArgumentError, "block required" if block.nil?
+      raise ArgumentError, "key must be a String, got #{key.inspect}" unless key.is_a?(String)
+      raise ArgumentError, "key cannot be empty" if key.empty?
+      if Keys.printable?(key)
+        raise ArgumentError,
+              "global shortcut key must be unprintable; got #{key.inspect}. " \
+              "Use Component#key_shortcut for printable keys (it's suppressed " \
+              "while a text widget owns the cursor, so it won't hijack typing)."
+      end
+      if [Keys::TAB, Keys::SHIFT_TAB].include?(key)
+        raise ArgumentError,
+              "#{key == Keys::TAB ? "TAB" : "SHIFT_TAB"} is reserved for focus navigation"
+      end
+      unless hint.nil? || hint.is_a?(String)
+        raise ArgumentError, "hint must be a String or nil, got #{hint.inspect}"
+      end
+
+      @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups, hint: hint)
+      refresh_status_bar
+    end
+
+    # Removes a shortcut previously installed by {#register_global_shortcut}.
+    # No-op if `key` was not registered.
+    # @param key [String]
+    # @return [void]
+    def unregister_global_shortcut(key)
+      @global_shortcuts.delete(key)
+      refresh_status_bar
+    end
+
     # @return [Component, nil] current active tiled component.
     def active_window
       check_locked
@@ -289,6 +410,14 @@ module Tuile
       @frame_buffer = +""
       begin
         until @invalidated.empty?
+          # Defensive filter: a component can become detached between enqueue
+          # and drain (popup close, sibling removed mid-event-handling, focus
+          # repair). Detached components have no place on the screen and must
+          # never paint, even though Component#invalidate already gates them
+          # out — this catches the case where attachment changed since.
+          @invalidated.delete_if { |c| !c.attached? }
+          break if @invalidated.empty?
+
           did_paint = true
           popups = @pane.popups
 
@@ -417,10 +546,17 @@ module Tuile
     # A key has been pressed on the keyboard. Handle it, or forward to active
     # window.
     #
-    # Tab / Shift+Tab are reserved navigation keys: intercepted here before
-    # the pane sees them, so a focused {Component::TextField} (which would
-    # otherwise swallow printable keys via the standard cursor-owner
-    # suppression) doesn't trap them.
+    # Dispatch order:
+    #   1. Tab / Shift+Tab — reserved focus navigation, intercepted before
+    #      anything else so a focused {Component::TextField} (which would
+    #      otherwise swallow printable keys via cursor-owner suppression)
+    #      doesn't trap them.
+    #   2. App-level shortcuts from {#register_global_shortcut}. An entry
+    #      registered with `over_popups: true` always fires; one with the
+    #      default `over_popups: false` fires only when no popup is open
+    #      (otherwise the popup receives the key normally).
+    #   3. {ScreenPane#handle_key}, which routes to the topmost popup or
+    #      tiled content.
     # @param key [String]
     # @return [Boolean] true if the key was handled by some window.
     def handle_key(key)
@@ -432,7 +568,13 @@ module Tuile
         focus_previous
         true
       else
-        @pane.handle_key(key)
+        shortcut = @global_shortcuts[key]
+        if !shortcut.nil? && (shortcut.over_popups || @pane.popups.empty?)
+          shortcut.block.call
+          true
+        else
+          @pane.handle_key(key)
+        end
       end
     end
 

data/lib/tuile/styled_string.rb

@@ -495,6 +495,19 @@ module Tuile
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bg: bg)) })
     end
 
+    # Returns a new {StyledString} with `fg` applied to every span, preserving
+    # each span's text and other style attributes (`bg`, `bold`, `italic`,
+    # `underline`). The new fg overlays without dropping background colors or
+    # text attributes the original styling carried.
+    #
+    # @param fg [Symbol, Integer, Array<Integer>, nil] foreground color, in
+    #   any of the forms accepted by {Style.new}. `nil` clears fg back to
+    #   the terminal default.
+    # @return [StyledString]
+    def with_fg(fg)
+      self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(fg: fg)) })
+    end
+
     # @return [String]
     def inspect
       "#<#{self.class.name} #{to_s.inspect}>"

data/lib/tuile/version.rb

@@ -2,5 +2,5 @@
 
 module Tuile
   # @return [String]
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end