tuile 0.13.0 → 0.14.0

data/lib/tuile/screen_pane.rb

@@ -13,7 +13,7 @@ module Tuile
   # The pane owns no chrome of its own — no status bar, no reserved row.
   # {#content} gets the full pane rect, and an app that wants a status line
   # builds one into its own layout and drives it from
-  # {Screen#on_focus_changed=} (`D-status-bar`).
+  # {Screen#on_focus_changed=} (`D_status_bar`).
   #
   # The pane is not a {Component::Layout}: popups deliberately overlap content
   # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
@@ -31,9 +31,10 @@ module Tuile
 
     # @return [Component, nil] the tiled content component.
     attr_reader :content
-    # @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.
+    # @return [Array<Component::Overlay>] the open overlays in stacking order;
+    #   last is topmost. Holds both {Component::Popup} modals and bare
+    #   {Component::Overlay}s ({Component::Overlay#modal?}). The array must not
+    #   be mutated by callers.
     attr_reader :popups
 
     def focusable? = false
@@ -54,21 +55,21 @@ module Tuile
       layout
     end
 
-    # 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.
+    # Adds an overlay and invalidates it for repaint. A {Component::Popup} is
+    # centered and grabs focus; a bare {Component::Overlay} is left wherever
+    # the caller positioned 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.
     #
-    # The *whole subtree* is invalidated, not just the popup wrapper (which
+    # The *whole subtree* is invalidated, not just the overlay wrapper (which
     # paints nothing on its own): a reopened popup may land on cells that the
     # tiled content has since overpainted, and if its rect is unchanged from
     # last time its content components won't re-invalidate themselves — so
-    # without this the popup's contents would stay blank on reopen.
-    # @param window [Component::Popup]
+    # without this the overlay's contents would stay blank on reopen.
+    # @param window [Component::Overlay] any overlay, modal or not.
     # @return [void]
     def add_popup(window)
-      raise TypeError, "expected Popup, got #{window.inspect}" unless window.is_a? Component::Popup
+      raise TypeError, "expected Overlay, got #{window.inspect}" unless window.is_a? Component::Overlay
       raise ArgumentError, "#{window} already has a parent #{window.parent}" unless window.parent.nil?
 
       @popup_prior_focus[window] = screen.focused
@@ -123,11 +124,11 @@ 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
+    # @return [Component::Popup, nil] the topmost modal overlay, or nil when
+    #   only bare {Component::Overlay}s (or none) are open. This is the "modal
     #   owner": the popup that scopes key dispatch, blocks mouse clicks, and
-    #   confines Tab cycling. Non-modal overlays are excluded — they float above
-    #   the content without capturing input.
+    #   confines Tab cycling. Bare 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.
@@ -139,7 +140,7 @@ module Tuile
     end
 
     # Gives {#content} the whole pane rect — the pane reserves nothing for
-    # itself. Each popup re-resolves its {Component::Popup#size} against the new
+    # itself. Each popup re-resolves its {Component::Popup#declared_size} against the new
     # screen via {Component::Popup#reposition} — so a {Fraction} size tracks
     # resize — repositioning itself (modal popups recenter; non-modal overlays
     # keep the top-left their owner assigned).
@@ -203,12 +204,12 @@ module Tuile
     # content beneath.
     #
     # A left click also *dismisses* the open popups it landed outside of that
-    # asked for it ({Component::Popup#close_on_outside_click?}). That is a
+    # asked for it ({Component::Overlay#close_on_outside_click?}). That is a
     # second thing happening on a click, but not a second dispatch: the click is
     # still delivered exactly once, down one chain, and a dismissed popup is
     # closed rather than told.
     #
-    # "Outside" is measured against the {Component::Popup#owner} chain, not
+    # "Outside" is measured against the {Component::Overlay#owner} chain, not
     # against one rect and not against stacking order: the popup the click hit
     # is kept, and so is every popup that one *belongs to*, transitively. That
     # is what stops a dialog being dismissed by a click on a dropdown its own
@@ -278,29 +279,30 @@ module Tuile
 
     private
 
-    # The popups a click counts as landing *inside*: the one it hit, plus every
-    # popup that one belongs to, up the {Component::Popup#owner} chain. An owner
-    # is any component, so it is resolved to the popup enclosing it (a popup
-    # resolves to itself) — which keeps the relationship a live tree question
-    # rather than one frozen when the overlay opened. The `include?` guard makes
-    # a mis-wired cycle terminate instead of hanging the UI thread.
-    # @param hit [Component::Popup, nil] the popup the click landed in, if any.
-    # @return [Array<Component::Popup>]
+    # The overlays a click counts as landing *inside*: the one it hit, plus
+    # every overlay that one belongs to, up the {Component::Overlay#owner}
+    # chain. An owner is any component, so it is resolved to the overlay
+    # enclosing it (an overlay resolves to itself) — which keeps the
+    # relationship a live tree question rather than one frozen when the overlay
+    # opened. The `include?` guard makes a mis-wired cycle terminate instead of
+    # hanging the UI thread.
+    # @param hit [Component::Overlay, nil] the overlay the click landed in, if any.
+    # @return [Array<Component::Overlay>]
     def kept_by(hit)
       kept = []
-      popup = hit
-      while popup && !kept.include?(popup)
-        kept << popup
-        popup = enclosing_popup(popup.owner)
+      overlay = hit
+      while overlay && !kept.include?(overlay)
+        kept << overlay
+        overlay = enclosing_popup(overlay.owner)
       end
       kept
     end
 
     # @param component [Component, nil]
-    # @return [Component::Popup, nil] `component` itself when it is a popup,
-    #   else the nearest popup above it, else nil.
+    # @return [Component::Overlay, nil] `component` itself when it is an
+    #   overlay, else the nearest overlay above it, else nil.
     def enclosing_popup(component)
-      component = component.parent until component.nil? || component.is_a?(Component::Popup)
+      component = component.parent until component.nil? || component.is_a?(Component::Overlay)
       component
     end
 

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`, `strikethrough`). Spans are non-overlapping and fully tile
+  # `underline`, `strikethrough`, `inverse`). Spans are non-overlapping and fully tile
   # the string — every character has exactly one resolved style, no overlay
   # layers to merge, so the style at any column is just its span's `style`
   # rather than a replay of the SGR state machine. The book's chapter 9 is
@@ -34,7 +34,7 @@ module Tuile
   # ## Parser
   #
   # {.parse} is strict by default — it recognizes only the SGR codes for
-  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough) and
+  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough/inverse) and
   # raises {ParseError} on anything else, keeping the `parse(to_ansi(x)) == x`
   # round-trip honest. Pass `lenient: true` to instead discard everything it
   # can't model (unmodeled SGR, cursor moves, OSC/DCS, stray escapes) and keep
@@ -62,17 +62,22 @@ module Tuile
     #   @return [Boolean]
     # @!attribute [r] strikethrough
     #   @return [Boolean]
-    class Style < Data.define(:fg, :bg, :bold, :italic, :underline, :strikethrough)
+    # @!attribute [r] inverse
+    #   @return [Boolean] swap the fg/bg *in effect* at the cell (SGR 7) —
+    #     including terminal defaults, which `fg`/`bg` can't name.
+    class Style < Data.define(:fg, :bg, :bold, :italic, :underline, :strikethrough, :inverse)
       # @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]
+      # @param inverse [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, strikethrough: false)
-        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:, strikethrough:)
+      def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false, strikethrough: false,
+                   inverse: false)
+        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:, strikethrough:, inverse:)
       end
 
       # The style with no color and no attributes — what the terminal shows
@@ -104,6 +109,7 @@ module Tuile
         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 << (other.inverse ? 7 : 27) if inverse != other.inverse
         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?
@@ -282,6 +288,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 7 then @style = @style.merge(inverse: true)
+          when 27 then @style = @style.merge(inverse: 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])
@@ -405,7 +413,7 @@ module Tuile
     # the parts of anything else. That is the one setting never wrong in the
     # dangerous direction: under-measuring lets a glyph overrun its cell, which
     # shifts the rest of the row, desyncs the cursor and escapes the component's
-    # rect, while over-measuring leaves a blank column. `D-cluster-width` has the
+    # rect, while over-measuring leaves a blank column. `D_cluster_width` has the
     # per-setting reasoning.
     # @return [Symbol]
     EMOJI_WIDTH = :rgi
@@ -605,6 +613,10 @@ module Tuile
     # so a log line keeps its red error-level bg while its plain text picks up an
     # inherited panel tint.
     #
+    # An `inverse` span counts as backgrounded and is skipped even when its `bg`
+    # member is nil: SGR 7 swaps the pair in effect, so a bg filled under it
+    # would recolor the span's *glyphs*, not the ground behind them.
+    #
     # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background color,
     #   coerced via {Color.coerce}. `nil` returns `self` unchanged.
     # @return [StyledString]
@@ -613,7 +625,11 @@ module Tuile
 
       bg = Color.coerce(bg)
       self.class.new(@spans.map do |span|
-        span.style.bg.nil? ? Span.new(text: span.text, style: span.style.merge(bg: bg)) : span
+        if span.style.bg.nil? && !span.style.inverse
+          Span.new(text: span.text, style: span.style.merge(bg: bg))
+        else
+          span
+        end
       end)
     end
 
@@ -670,6 +686,23 @@ module Tuile
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(underline:)) })
     end
 
+    # Returns a new {StyledString} with `inverse` applied to every span,
+    # preserving each span's text and other style attributes. Inverse swaps
+    # whatever fg/bg are actually in effect at each cell — terminal defaults
+    # included — so a focus chip built with it reads as "backgrounded" on any
+    # terminal palette without picking a single color:
+    #
+    #   StyledString.plain(" 1 VMs ").with_inverse   # the inverted-chip idiom
+    #
+    # There is deliberately no `under_inverse`, for the reason {#with_bold}
+    # spells out. Pass `inverse: false` to clear it.
+    #
+    # @param inverse [Boolean] whether the spans should be inverted.
+    # @return [StyledString]
+    def with_inverse(inverse: true)
+      self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(inverse:)) })
+    end
+
     # @return [String]
     def inspect
       "#<#{self.class.name} #{to_s.inspect}>"

data/lib/tuile/terminal_background.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Tuile
-  # Detects whether the terminal background is light or dark, so {Screen}
-  # can pick {Theme::LIGHT} or {Theme::DARK} automatically at startup.
+  # Detects the terminal's background color — both the light/dark scheme
+  # {Screen} picks {Theme::LIGHT} or {Theme::DARK} from, and, when the
+  # terminal answers the query, the actual RGB behind it.
   #
   # Two mechanisms, in order of reliability:
   #
@@ -15,14 +16,34 @@ module Tuile
   #    bounded by a short timeout.
   # 2. **`COLORFGBG` env var** — rxvt/konsole export `"fg;bg"` ANSI palette
   #    indices. Less reliable (stale across SSH/tmux, often unset); used
-  #    only when OSC 11 yields nothing.
+  #    only when OSC 11 yields nothing. Palette indices carry no RGB, so
+  #    this path fills in {Result#scheme} and leaves {Result#color} nil.
   #
   # **Timing matters**: the OSC 11 reply arrives on stdin, so the query
   # must complete before {EventQueue#start_key_thread} owns stdin —
   # otherwise the reply bytes get consumed as garbage keystrokes. {Screen}
   # calls {.detect} from its constructor, which apps run before
   # {Screen#run_event_loop}; don't call this after the event loop started.
+  #
+  # Once the loop *is* running the query is still available, from the other
+  # side: {Screen} writes {QUERY} on every OS appearance flip and the key
+  # thread — which owns stdin by then — reads the reply back through
+  # {Keys.getkey} and {.parse}. See {Screen#background_color}.
   module TerminalBackground
+    # What a detection found: the light/dark `scheme`, and the background
+    # `color` when a terminal actually reported one.
+    #
+    # `color` is nil whenever the scheme came from the `COLORFGBG`
+    # fallback, so a consumer deriving a tint from the background must
+    # handle nil — plenty of terminals answer neither query.
+    #
+    # @!attribute [r] scheme
+    #   @return [Symbol] `:light` or `:dark`.
+    # @!attribute [r] color
+    #   @return [Color, nil] the reported background as 24-bit RGB, or nil
+    #     when only `COLORFGBG` answered.
+    Result = Data.define(:scheme, :color)
+
     # How long to wait for the OSC 11 reply. Generous for a local
     # terminal; bounded so unsupporting terminals (which never reply)
     # don't stall startup.
@@ -54,35 +75,63 @@ module Tuile
       # Detects the terminal background. Queries OSC 11 when both `input`
       # and `output` are TTYs, falling back to `COLORFGBG`.
       #
+      #   TerminalBackground.detect
+      #   # => #<data Result scheme=:dark, color=#<Tuile::Color [30, 30, 46]>>
+      #
       # @param input [IO] where the OSC 11 reply arrives (the TTY input).
       # @param output [IO] where the query is written (the TTY output).
       # @param env [Hash{String => String}] environment for the `COLORFGBG`
       #   fallback; defaults to `ENV` (which duck-types the `[]` lookup).
       # @param timeout [Numeric] max seconds to wait for the OSC 11 reply.
-      # @return [Symbol, nil] `:light`, `:dark`, or nil when undetectable.
+      # @return [Result, nil] nil when the background is undetectable —
+      #   neither mechanism answered.
       def detect(input: $stdin, output: $stdout, env: ENV, timeout: QUERY_TIMEOUT)
         osc = query_osc11(input, output, timeout) if input.tty? && output.tty?
-        osc || from_colorfgbg(env["COLORFGBG"])
+        return osc if osc
+
+        scheme = from_colorfgbg(env["COLORFGBG"])
+        scheme && Result.new(scheme: scheme, color: nil)
+      end
+
+      # Parses an OSC 11 reply — the terminal's answer to {QUERY}, matched
+      # anywhere in `reply`.
+      #
+      #   TerminalBackground.parse("\e]11;rgb:1e1e/1e1e/2e2e\a").color
+      #   # => #<Tuile::Color [30, 30, 46]>
+      #
+      # Public because a reply also arrives *mid-session*, long after
+      # {.detect}'s own bounded read: once the key thread owns stdin, a
+      # whole reply surfaces as one "key" from {Keys.getkey}.
+      #
+      # @param reply [String] raw terminal output that may contain a reply.
+      # @return [Result, nil] nil when `reply` holds no OSC 11 reply.
+      def parse(reply)
+        match = REPLY.match(reply)
+        return nil unless match
+
+        # Components arrive as 1–4 hex digits (terminals vary), so each is
+        # scaled by its own width: "ab" and "abab" are both ~0.67.
+        components = match.captures.map { |c| c.to_i(16).fdiv((16**c.length) - 1) }
+        Result.new(scheme: classify(components), color: to_color(components))
       end
 
       private
 
-      # Writes the OSC 11 query and classifies the reply. The whole
-      # exchange runs with `input` in raw mode: the reply has no trailing
-      # newline, so a canonical-mode read would block past the timeout,
-      # and echo would smear the reply bytes onto the screen.
+      # Writes the OSC 11 query and parses the reply. The whole exchange
+      # runs with `input` in raw mode: the reply has no trailing newline,
+      # so a canonical-mode read would block past the timeout, and echo
+      # would smear the reply bytes onto the screen.
       # @param input [IO]
       # @param output [IO]
       # @param timeout [Numeric]
-      # @return [Symbol, nil]
+      # @return [Result, nil]
       def query_osc11(input, output, timeout)
         reply = input.raw do
           output.write(QUERY)
           output.flush
           read_reply(input, timeout)
         end
-        match = REPLY.match(reply)
-        match && classify(match.captures)
+        parse(reply)
       rescue SystemCallError, IOError
         nil
       end
@@ -107,16 +156,25 @@ module Tuile
         buffer
       end
 
-      # Relative luminance of the reported background, scaled per
-      # component hex width (xterm replies 4 digits per channel, others 2).
-      # @param components [Array<String>] three hex strings.
+      # Light or dark, by relative luminance against a 0.5 threshold.
+      # @param components [Array<Float>] red, green and blue, each 0.0..1.0.
       # @return [Symbol] `:light` or `:dark`.
       def classify(components)
-        r, g, b = components.map { |c| c.to_i(16).fdiv((16**c.length) - 1) }
+        r, g, b = components
         luminance = (0.2126 * r) + (0.7152 * g) + (0.0722 * b)
         luminance > 0.5 ? :light : :dark
       end
 
+      # The reported background as a 24-bit {Color}. Quantizing xterm's
+      # 16-bit-per-channel reply down to 8 loses nothing a terminal can
+      # display, and keeps the exposed value in the type the rest of Tuile
+      # paints with.
+      # @param components [Array<Float>] red, green and blue, each 0.0..1.0.
+      # @return [Color]
+      def to_color(components)
+        Color.rgb(*components.map { (_1 * 255).round })
+      end
+
       # `COLORFGBG` is `"fg;bg"` (rxvt sometimes `"fg;default;bg"`) with
       # ANSI palette indices. White-ish backgrounds — 7 (white) and the
       # bright range 9–15 — read as light; 0–6 and 8 as dark; anything

data/lib/tuile/version.rb

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