tuile 0.6.0 → 0.8.0

data/lib/tuile/screen_pane.rb

@@ -28,8 +28,9 @@ module Tuile
 
     # @return [Component, nil] the tiled content component.
     attr_reader :content
-    # @return [Array<Component>] modal popups in stacking order; last is
-    #   topmost. The array must not be mutated by callers.
+    # @return [Array<Component>] overlay popups in stacking order; last is
+    #   topmost. Holds both modal popups and non-modal overlays
+    #   ({Component::Popup#modal?}). The array must not be mutated by callers.
     attr_reader :popups
     # @return [Component::Label] the bottom status bar.
     attr_reader :status_bar
@@ -57,7 +58,11 @@ module Tuile
       layout
     end
 
-    # Adds a popup, centers it, focuses it, and invalidates it for repaint.
+    # Adds a popup and invalidates it for repaint. A modal popup is centered
+    # and grabs focus; a non-modal overlay ({Component::Popup#modal?} false) is
+    # left wherever the caller positions it and does *not* take focus, so the
+    # component that was focused keeps the cursor and keeps receiving keys —
+    # the overlay floats above the content, driven from app code.
     # @param window [Component::Popup]
     # @return [void]
     def add_popup(window)
@@ -67,8 +72,10 @@ module Tuile
       @popup_prior_focus[window] = screen.focused
       @popups << window
       window.parent = self
-      window.center
-      screen.focused = window
+      if window.modal?
+        window.center
+        screen.focused = window
+      end
       screen.invalidate(window)
     end
 
@@ -100,6 +107,13 @@ module Tuile
     # @return [Boolean] true if this pane currently hosts the popup.
     def has_popup?(window) = @popups.include?(window) # rubocop:disable Naming/PredicatePrefix
 
+    # @return [Component::Popup, nil] the topmost *modal* popup, or nil when
+    #   only non-modal overlays (or no popups) are open. This is the "modal
+    #   owner": the popup that scopes key dispatch, blocks mouse clicks, owns
+    #   the status bar, and confines Tab cycling. Non-modal overlays are
+    #   excluded — they float above the content without capturing input.
+    def modal_popup = @popups.reverse_each.find(&:modal?)
+
     # Re-lays out children whenever the pane's own rect changes.
     # @param new_rect [Rect]
     # @return [void]
@@ -109,13 +123,14 @@ module Tuile
     end
 
     # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Popups self-position via {Component::Popup#center}.
+    # (bottom row). Modal popups self-recenter via {Component::Popup#center};
+    # non-modal overlays keep the position their owner assigned.
     # @return [void]
     def layout
       return if rect.empty?
 
       @content.rect = Rect.new(rect.left, rect.top, rect.width, [rect.height - 1, 0].max) unless @content.nil?
-      @popups.each(&:center)
+      @popups.each { |p| p.center if p.modal? }
       @status_bar.rect = Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
     end
 
@@ -123,32 +138,55 @@ module Tuile
     # @return [void]
     def repaint; end
 
-    # Topmost popup is modal: it eats keys. Falls through to content only
-    # when no popup is open.
+    # Dispatches a key in two phases, both scoped to the topmost *modal* popup
+    # (when one is open) or else the tiled {#content}. Non-modal overlays are
+    # never the scope: focus stays in the content beneath them, and the overlay
+    # is driven by app code (which forwards keys to it explicitly), so it
+    # doesn't appear in this path at all.
+    #
+    # 1. *Capture* — a {Component#key_shortcut} match anywhere in the scope
+    #    focuses that component and consumes the key. Suppressed while a
+    #    cursor-owner ({Screen#cursor_position}) is mid-edit, so typing into a
+    #    {Component::TextField} isn't hijacked by a sibling's shortcut.
+    # 2. *Delivery* — the key is handed to {Screen#focused} and bubbles up its
+    #    ancestor chain to the scope root; the first component to return true
+    #    wins. Focus that is nil or sits outside the scope receives nothing,
+    #    which is what keeps an open modal popup modal.
+    # @param key [String]
+    # @return [Boolean] true if the key was handled.
     def handle_key(key)
-      topmost = @popups.last
-      return topmost.handle_key(key) unless topmost.nil?
-      return @content.handle_key(key) unless @content.nil?
+      scope = modal_popup || @content
+      return false if scope.nil?
 
-      false
+      if screen.cursor_position.nil?
+        target = scope.find_shortcut_component(key)
+        unless target.nil?
+          screen.focused = target
+          return true
+        end
+      end
+
+      bubble_key(key, scope)
     end
 
     # Mouse events check popups in reverse stacking order (topmost first), and
-    # fall through to content only when no popup is hit *and* there are no
-    # popups open. This preserves modal click-blocking: an open popup eats
-    # clicks even outside its rect.
+    # fall through to content only when no popup is hit *and* no modal popup is
+    # open. This preserves modal click-blocking — an open modal eats clicks
+    # even outside its rect — while a non-modal overlay blocks nothing: clicks
+    # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
+    # content beneath.
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
-      clicked = @popups.reverse_each.find { it.rect.contains?(event.point) }
-      clicked = @content if clicked.nil? && @popups.empty?
+      clicked = @popups.reverse_each.find { _1.rect.contains?(event.point) }
+      clicked = @content if clicked.nil? && modal_popup.nil?
       clicked&.handle_mouse(event)
     end
 
     # Focus repair when a child detaches. Default {Component#on_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
     # Instead, route focus to the first interactable widget in the now-topmost
-    # popup; falling back to the focus snapshotted when this popup was opened
+    # modal popup; falling back to the focus snapshotted when this popup was opened
     # (if still attached and still focusable); then to the first interactable
     # widget in {#content}; then to {#content} itself; then nil.
     #
@@ -167,7 +205,7 @@ module Tuile
       cursor = f
       while cursor
         if cursor == child
-          fallback = first_tab_stop_or_root(@popups.last)
+          fallback = first_tab_stop_or_root(modal_popup)
           if fallback.nil? && @removing_popup_prior&.attached? && @removing_popup_prior.focusable?
             fallback = @removing_popup_prior
           end
@@ -181,6 +219,29 @@ module Tuile
 
     private
 
+    # Delivers `key` to {Screen#focused} and bubbles it up the ancestor chain,
+    # stopping at (and including) `scope`. Delivers to no one — returning false
+    # — when focus is nil or sits outside `scope`; the latter is what makes an
+    # open popup modal, since focus is always inside it and content beneath
+    # never receives keys.
+    # @param key [String]
+    # @param scope [Component] the modal scope root (topmost popup or content).
+    # @return [Boolean] true if some component on the chain handled the key.
+    def bubble_key(key, scope)
+      chain = []
+      cursor = screen.focused
+      until cursor.nil?
+        chain << cursor
+        break if cursor.equal?(scope)
+
+        cursor = cursor.parent
+      end
+      return false unless chain.last.equal?(scope)
+
+      chain.each { |c| return true if c.handle_key(key) }
+      false
+    end
+
     # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling
     # back to `root` itself when the subtree has no tab stops. Returns `nil`
     # if `root` is `nil`.

data/lib/tuile/styled_string.rb

@@ -3,7 +3,7 @@
 module Tuile
   # An immutable string-with-styling, modeled as a sequence of {Span}s where
   # each span carries a complete {Style} (`fg`, `bg`, `bold`, `italic`,
-  # `underline`). Spans are non-overlapping and fully tile the string — every
+  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile the string — every
   # character has exactly one resolved style, no overlay layers to merge.
   #
   # Where this differs from threading SGR escapes through a plain `String`:
@@ -43,12 +43,21 @@ module Tuile
   #
   # ## Parser
   #
-  # {.parse} is strict by design: it recognizes only the SGR codes
+  # {.parse} is strict by default: it recognizes only the SGR codes
   # corresponding to {Style}'s supported attributes (fg/bg/bold/italic/
-  # underline). Anything else — unmodeled attributes (dim, blink, reverse,
-  # strike, conceal, double-underline, overline, ...), unknown SGR codes, or
+  # underline/strikethrough). Anything else — unmodeled attributes (dim, blink,
+  # reverse, conceal, double-underline, overline, ...), unknown SGR codes, or
   # non-SGR escapes (cursor moves, OSC) — raises {ParseError}. This keeps the
   # round-trip parse(to_ansi(x)) == x contract honest.
+  #
+  # Pass `lenient: true` to instead **discard** everything the parser can't
+  # model and keep going — recognized fg/bg/bold/italic/underline/strikethrough codes still
+  # apply, and any unmodeled SGR code, malformed extended color, non-SGR CSI
+  # (cursor moves, `\e[K`), OSC/DCS/string sequence, or stray escape is
+  # silently dropped. This is the mode for piping in colored output you don't
+  # control (e.g. `git --color` through a pager): "give me the colors, throw
+  # the rest away." It is lossy by design — `parse(x, lenient: true)` does not
+  # round-trip back to `x`.
   class StyledString
     # Raised by {.parse} on malformed or unsupported escape sequences.
     class ParseError < Error; end
@@ -69,16 +78,19 @@ module Tuile
     #   @return [Boolean]
     # @!attribute [r] underline
     #   @return [Boolean]
-    class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
+    # @!attribute [r] strikethrough
+    #   @return [Boolean]
+    class Style < Data.define(:fg, :bg, :bold, :italic, :underline, :strikethrough)
       # @param fg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bold [Boolean]
       # @param italic [Boolean]
       # @param underline [Boolean]
+      # @param strikethrough [Boolean]
       # @return [Style]
       # @raise [ArgumentError] when a color is not one of the accepted forms.
-      def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
-        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:)
+      def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false, strikethrough: false)
+        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:, strikethrough:)
       end
 
       # The style with no color and no attributes — what the terminal shows
@@ -93,6 +105,45 @@ module Tuile
       # @param overrides [Hash{Symbol => Object}]
       # @return [Style]
       def merge(**overrides) = self.class.new(**to_h.merge(overrides))
+
+      # Minimal SGR escape that transitions a terminal already showing `self`
+      # into `other`: only the attributes that differ are emitted. Returns
+      # `""` when the styles are identical (nothing to do), and {Ansi::RESET}
+      # (`\e[0m`, one code) when `other` is the default style — shorter than
+      # turning each attribute off individually.
+      #
+      # Shared by {StyledString#to_ansi} (diffing span-to-span from the default
+      # style) and {Buffer}'s flush (diffing cell-to-cell against the style the
+      # terminal currently holds), so both emit identical minimal sequences.
+      # @param other [Style] the style to transition to.
+      # @return [String]
+      def sgr_to(other)
+        return "" if self == other
+        return Ansi::RESET if other.default?
+
+        codes = []
+        codes << (other.bold ? 1 : 22) if bold != other.bold
+        codes << (other.italic ? 3 : 23) if italic != other.italic
+        codes << (other.underline ? 4 : 24) if underline != other.underline
+        codes << (other.strikethrough ? 9 : 29) if strikethrough != other.strikethrough
+        codes.concat(color_codes(other.fg, target: :fg)) if fg != other.fg
+        codes.concat(color_codes(other.bg, target: :bg)) if bg != other.bg
+        return "" if codes.empty?
+
+        "\e[#{codes.join(";")}m"
+      end
+
+      private
+
+      # @param color [Color, nil]
+      # @param target [Symbol] either `:fg` or `:bg`.
+      # @return [Array<Integer>] SGR codes; `[39]` / `[49]` for the "default"
+      #   reset when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
+      def color_codes(color, target:)
+        return [target == :fg ? 39 : 49] if color.nil?
+
+        color.sgr_codes(target)
+      end
     end
 
     # A maximal run of text sharing a single {Style}. `text` is plain — it
@@ -117,8 +168,9 @@ module Tuile
     # @api private
     # Hand-rolled SGR parser. State machine over a {StringScanner}: plain
     # text accumulates into the current span; each `\e[...m` flushes the
-    # current span and updates the running {Style}. Anything outside the
-    # supported SGR alphabet raises {ParseError}.
+    # current span and updates the running {Style}. In strict mode anything
+    # outside the supported SGR alphabet raises {ParseError}; in lenient mode
+    # it is consumed and discarded (see {StyledString} "## Parser").
     class Parser
       # @return [Array<Symbol>]
       STANDARD_COLORS = Color::COLOR_SYMBOLS[0, 8].freeze
@@ -128,9 +180,20 @@ module Tuile
       BRIGHT_COLORS = Color::COLOR_SYMBOLS[8, 8].freeze
       private_constant :BRIGHT_COLORS
 
+      # ESC-introducers (the byte after `\e`) whose payload runs until a string
+      # terminator (ST `\e\\` or BEL): OSC `]`, DCS `P`, SOS `X`, PM `^`,
+      # APC `_`. In lenient mode the whole sequence — payload included — is
+      # swallowed so it never leaks into span text.
+      # @return [Array<String>]
+      STRING_INTRODUCERS = %w(] P X ^ _).freeze
+      private_constant :STRING_INTRODUCERS
+
       # @param input [String]
-      def initialize(input)
+      # @param lenient [Boolean] when true, discard unmodeled SGR codes and
+      #   non-SGR escapes instead of raising {ParseError}.
+      def initialize(input, lenient: false)
         @scanner = StringScanner.new(input)
+        @lenient = lenient
         @style = Style::DEFAULT
         @text = +""
         @spans = []
@@ -160,16 +223,70 @@ module Tuile
       # @return [void]
       def consume_escape
         @scanner.getch # \e
-        bracket = @scanner.getch
-        raise ParseError, "expected '[' after ESC, got #{bracket.inspect}" if bracket != "["
+        intro = @scanner.getch
+        case intro
+        when "[" then consume_csi
+        when nil then raise ParseError, "unterminated escape sequence" unless @lenient
+        else
+          raise ParseError, "expected '[' after ESC, got #{intro.inspect}" unless @lenient
+
+          consume_non_csi(intro)
+        end
+      end
 
-        params = @scanner.scan(/[\d;]*/) || ""
+      # Consumes a CSI sequence (`\e[` already eaten). A well-formed SGR
+      # (`\e[...m` with numeric/`;` params and no intermediates) is applied;
+      # anything else is a non-SGR or malformed CSI — raises in strict mode,
+      # swallowed in lenient. Scans the full CSI grammar (parameter bytes
+      # `\x30-\x3F`, intermediate bytes `\x20-\x2F`, final byte) so lenient
+      # mode consumes the whole sequence even for private-marker forms like
+      # `\e[?25l`.
+      # @return [void]
+      def consume_csi
+        params = @scanner.scan(/[\x30-\x3F]*/) || ""
+        intermediates = @scanner.scan(/[\x20-\x2F]*/) || ""
         final = @scanner.getch
-        raise ParseError, "unterminated escape sequence" if final.nil?
-        raise ParseError, "non-SGR CSI sequence (final byte #{final.inspect})" if final != "m"
+
+        if final == "m" && intermediates.empty? && params.match?(/\A[\d;]*\z/)
+          flush
+          return apply_sgr(params)
+        end
+
+        raise ParseError, "unterminated escape sequence" if final.nil? && !@lenient
+        raise ParseError, "non-SGR CSI sequence (final byte #{final.inspect})" unless @lenient
 
         flush
-        apply_sgr(params)
+      end
+
+      # Lenient-only: discards a non-CSI escape (`\e` and `intro` already
+      # eaten). OSC/DCS/string sequences run to their string terminator; an
+      # nF escape (`\e( B`) eats its intermediates plus one final byte; any
+      # other Fe/Fp/Fs escape was complete in `intro` alone.
+      # @param intro [String] the byte after `\e` (never `"["`).
+      # @return [void]
+      def consume_non_csi(intro)
+        flush
+        if STRING_INTRODUCERS.include?(intro)
+          consume_string_sequence
+        elsif intro.match?(/[\x20-\x2F]/)
+          @scanner.scan(/[\x20-\x2F]*/)
+          @scanner.getch
+        end
+      end
+
+      # Lenient-only: swallows an OSC/DCS/string-sequence payload up to and
+      # including its terminator (BEL, or ST `\e\\`), or to EOS if unterminated.
+      # @return [void]
+      def consume_string_sequence
+        until @scanner.eos?
+          ch = @scanner.getch
+          break if ch == "\a"
+
+          if ch == "\e"
+            @scanner.getch if @scanner.peek(1) == "\\"
+            break
+          end
+        end
       end
 
       # @param params_str [String]
@@ -187,6 +304,8 @@ module Tuile
           when 23 then @style = @style.merge(italic: false)
           when 4 then @style = @style.merge(underline: true)
           when 24 then @style = @style.merge(underline: false)
+          when 9 then @style = @style.merge(strikethrough: true)
+          when 29 then @style = @style.merge(strikethrough: false)
           when 30..37 then @style = @style.merge(fg: STANDARD_COLORS[code - 30])
           when 38
             i += consume_extended_color(codes, i, :fg)
@@ -199,7 +318,7 @@ module Tuile
           when 49 then @style = @style.merge(bg: nil)
           when 90..97 then @style = @style.merge(fg: BRIGHT_COLORS[code - 90])
           when 100..107 then @style = @style.merge(bg: BRIGHT_COLORS[code - 100])
-          else raise ParseError, "unsupported SGR code #{code}"
+          else raise ParseError, "unsupported SGR code #{code}" unless @lenient
           end
           i += 1
         end
@@ -208,27 +327,37 @@ module Tuile
       # @param codes [Array<Integer>]
       # @param index [Integer]
       # @param target [Symbol] either `:fg` or `:bg`.
-      # @return [Integer] how many SGR codes were consumed (3 for 256-color, 5 for RGB).
+      # @return [Integer] how many SGR codes were consumed. In lenient mode a
+      #   malformed color is skipped rather than applied, but the same count is
+      #   returned (3 for 256-color, 5 for RGB) so the running index advances
+      #   past its operands; an unknown selector skips just `38`/`48` + the
+      #   selector byte (2), letting the rest be reprocessed.
       def consume_extended_color(codes, index, target)
         mode = codes[index + 1]
         case mode
         when 5
           n = codes[index + 2]
-          raise ParseError, "invalid 256-color index #{n.inspect}" unless n&.between?(0, 255)
-
-          @style = @style.merge(target => n)
+          if n&.between?(0, 255)
+            @style = @style.merge(target => n)
+          elsif !@lenient
+            raise ParseError, "invalid 256-color index #{n.inspect}"
+          end
           3
         when 2
           r = codes[index + 2]
           g = codes[index + 3]
           b = codes[index + 4]
-          [r, g, b].each do |v|
-            raise ParseError, "invalid RGB component #{v.inspect}" unless v&.between?(0, 255)
+          if [r, g, b].all? { |v| v&.between?(0, 255) }
+            @style = @style.merge(target => [r, g, b])
+          elsif !@lenient
+            bad = [r, g, b].find { |v| !v&.between?(0, 255) }
+            raise ParseError, "invalid RGB component #{bad.inspect}"
           end
-          @style = @style.merge(target => [r, g, b])
           5
         else
-          raise ParseError, "unsupported extended-color selector #{mode.inspect}"
+          raise ParseError, "unsupported extended-color selector #{mode.inspect}" unless @lenient
+
+          2
         end
       end
 
@@ -268,10 +397,14 @@ module Tuile
       # default-styled span.
       #
       # @param input [String, StyledString, nil]
+      # @param lenient [Boolean] when true, unmodeled SGR codes and non-SGR
+      #   escapes are discarded instead of raising — see {StyledString}
+      #   "## Parser". Lossy: the result no longer round-trips to `input`.
       # @return [StyledString]
-      # @raise [ParseError] on unsupported or malformed escape sequences.
+      # @raise [ParseError] on unsupported or malformed escape sequences
+      #   (strict mode only).
       # @raise [TypeError] when `input` is none of String, StyledString, nil.
-      def parse(input)
+      def parse(input, lenient: false)
         case input
         when nil then EMPTY
         when StyledString then input
@@ -279,7 +412,7 @@ module Tuile
           return EMPTY if input.empty?
           return new([Span.new(text: input, style: Style::DEFAULT)]) unless input.include?("\e")
 
-          Parser.new(input).parse
+          Parser.new(input, lenient:).parse
         else
           raise TypeError, "cannot parse #{input.class}"
         end
@@ -456,7 +589,7 @@ module Tuile
 
     # Returns a new {StyledString} with `bg` applied to every span, preserving
     # each span's text and other style attributes (`fg`, `bold`, `italic`,
-    # `underline`). Useful for row-level highlights — the new bg overlays
+    # `underline`, `strikethrough`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     #
     # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background
@@ -469,7 +602,7 @@ module Tuile
 
     # 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
+    # `underline`, `strikethrough`). The new fg overlays without dropping background colors or
     # text attributes the original styling carried.
     #
     # @param fg [Color, Symbol, Integer, Array<Integer>, nil] foreground
@@ -492,7 +625,7 @@ module Tuile
       out = +""
       current = Style::DEFAULT
       @spans.each do |span|
-        out << sgr_diff(current, span.style)
+        out << current.sgr_to(span.style)
         out << span.text
         current = span.style
       end
@@ -517,34 +650,6 @@ module Tuile
       result
     end
 
-    # @param from [Style]
-    # @param to [Style]
-    # @return [String]
-    def sgr_diff(from, to)
-      return "" if from == to
-      return Ansi::RESET if to.default?
-
-      codes = []
-      codes << (to.bold ? 1 : 22) if from.bold != to.bold
-      codes << (to.italic ? 3 : 23) if from.italic != to.italic
-      codes << (to.underline ? 4 : 24) if from.underline != to.underline
-      codes.concat(color_codes(to.fg, target: :fg)) if from.fg != to.fg
-      codes.concat(color_codes(to.bg, target: :bg)) if from.bg != to.bg
-      return "" if codes.empty?
-
-      "\e[#{codes.join(";")}m"
-    end
-
-    # @param color [Color, nil]
-    # @param target [Symbol] `:fg` or `:bg`.
-    # @return [Array<Integer>] SGR codes; `[39]` / `[49]` for the "default" reset
-    #   when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
-    def color_codes(color, target:)
-      return [target == :fg ? 39 : 49] if color.nil?
-
-      color.sgr_codes(target)
-    end
-
     # @param start_or_range [Integer, Range]
     # @param len [Integer, nil]
     # @param total [Integer] receiver's full display width.

data/lib/tuile/version.rb

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

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.3"