tuile 0.11.0 → 0.13.0

data/lib/tuile/screen_pane.rb

@@ -5,10 +5,15 @@ module Tuile
   #
   # {Screen} is a singleton runtime owner (event loop, lock, terminal IO,
   # invalidation set). All actual UI lives under a {ScreenPane}: the tiled
-  # {#content}, the modal {#popups} stack, and the bottom {#status_bar}.
-  # Putting them under a single Component parent gives focus traversal a real
-  # root, makes {Component#attached?} a one-liner, and lets popup-focus repair
-  # fall out of the standard {Component#on_child_removed} hook.
+  # {#content} and the {#popups} stack. Putting them under a single Component
+  # parent gives focus traversal a real root, makes {Component#attached?} a
+  # one-liner, and lets popup-focus repair fall out of the standard
+  # {Component#on_child_removed} hook.
+  #
+  # 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`).
   #
   # The pane is not a {Component::Layout}: popups deliberately overlap content
   # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
@@ -22,10 +27,6 @@ module Tuile
       # user was, instead of falling through to {#content} and getting
       # cascaded to the first focusable child.
       @popup_prior_focus = {}
-      @status_bar = Component::Label.new
-      # Added first and never removed, so it is always the last child — which is
-      # the anchor `add_popup` inserts against.
-      add_child(@status_bar)
     end
 
     # @return [Component, nil] the tiled content component.
@@ -34,8 +35,6 @@ module Tuile
     #   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
 
     def focusable? = false
 
@@ -74,7 +73,7 @@ module Tuile
 
       @popup_prior_focus[window] = screen.focused
       @popups << window
-      add_child(window, at: @children.index(@status_bar))
+      add_child(window) # appended: popups paint over the tiled content
       if window.modal?
         window.center
         screen.focused = window
@@ -126,9 +125,9 @@ module Tuile
 
     # @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.
+    #   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.
     def modal_popup = @popups.reverse_each.find(&:modal?)
 
     # Re-lays out children whenever the pane's own rect changes.
@@ -139,18 +138,17 @@ module Tuile
       layout
     end
 
-    # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Each popup re-resolves its {Component::Popup#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).
+    # Gives {#content} the whole pane rect — the pane reserves nothing for
+    # itself. Each popup re-resolves its {Component::Popup#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).
     # @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?
+      @content&.rect = rect
       @popups.each(&:reposition)
-      @status_bar.rect = Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
     end
 
     # Pane paints nothing itself; its children paint over the entire rect.
@@ -181,18 +179,67 @@ module Tuile
       bubble_key(key, scope)
     end
 
+    # Delivers pasted text along the same focus chain {#handle_key} bubbles
+    # along, and with the same scoping — first {Component#handle_paste}
+    # returning true wins.
+    # @param text [String]
+    # @return [Boolean] true if the text was consumed.
+    def handle_paste(text)
+      scope = modal_popup || @content
+      return false if scope.nil?
+
+      chain = focus_chain(scope)
+      return false if chain.nil?
+
+      chain.each { |c| return true if c.handle_paste(text) }
+      false
+    end
+
     # Mouse events check popups in reverse stacking order (topmost first), and
     # 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.
+    #
+    # 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
+    # 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
+    # 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
+    # field opened, and a menu cascade being dismissed by a click on one of its
+    # own deeper panels. Order carries no meaning here — between unrelated
+    # overlays it is merely the order they opened in — so ownership is declared
+    # rather than inferred from the stack.
+    #
+    # Two halves of the ordering are load-bearing, and both are specced:
+    #
+    # - **Snapshot before routing.** A popup the delivered click *opens* must
+    #   not be in the set (it would immediately dismiss itself — every
+    #   {Component::Select} would be unopenable by mouse).
+    # - **Close after routing.** A widget toggling its own overlay from a click
+    #   on its face closes it during delivery, and {Component::Popup#close} is
+    #   idempotent, so the dismissal no-ops. Close *first* and the widget sees
+    #   a shut overlay and reopens it — a Select's dropdown could then never be
+    #   dismissed by clicking the Select.
+    #
+    # The snapshot is a fresh array for a third reason: a handler may close
+    # further popups, and `@popups` must not be mutated mid-iteration.
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
-      clicked = @popups.reverse_each.find { _1.rect.contains?(event.point) }
-      clicked = @content if clicked.nil? && modal_popup.nil?
+      hit = @popups.reverse_each.find { _1.rect.contains?(event.point) }
+      dismissable = event.button == :left ? @popups - kept_by(hit) : []
+
+      clicked = hit || (@content if modal_popup.nil?)
       clicked&.handle_mouse(event)
+
+      dismissable.each { _1.close if _1.close_on_outside_click? }
     end
 
     # Focus repair when a child detaches. Default {Component#on_child_removed}
@@ -231,6 +278,32 @@ 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>]
+    def kept_by(hit)
+      kept = []
+      popup = hit
+      while popup && !kept.include?(popup)
+        kept << popup
+        popup = enclosing_popup(popup.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.
+    def enclosing_popup(component)
+      component = component.parent until component.nil? || component.is_a?(Component::Popup)
+      component
+    end
+
     # 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
@@ -240,6 +313,18 @@ module Tuile
     # @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 = focus_chain(scope)
+      return false if chain.nil?
+
+      chain.each { |c| return true if c.handle_key(key) }
+      false
+    end
+
+    # {Screen#focused} and its ancestors up to and including `scope`.
+    # @param scope [Component] the modal scope root (topmost popup or content).
+    # @return [Array<Component>, nil] the chain, innermost first; nil when
+    #   focus is nil or sits outside `scope`.
+    def focus_chain(scope)
       chain = []
       cursor = screen.focused
       until cursor.nil?
@@ -248,10 +333,7 @@ module Tuile
 
         cursor = cursor.parent
       end
-      return false unless chain.last.equal?(scope)
-
-      chain.each { |c| return true if c.handle_key(key) }
-      false
+      chain.last.equal?(scope) ? chain : nil
     end
 
     # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling

data/lib/tuile/styled_string.rb

@@ -536,7 +536,7 @@ module Tuile
       result
     end
 
-    # Word-wraps to physical lines that each fit within `width` display
+    # Word-wraps to rows that each fit within `width` display
     # columns, preserving spans and styles across breaks. Greedy word-wrap,
     # hard-break for words wider than `width`, leading whitespace dropped on
     # wrapped continuations, hard `"\n"` breaks preserved as separate output
@@ -560,16 +560,16 @@ module Tuile
     # @param width [Integer, nil] target column width. `nil` or `<= 0` skips
     #   wrapping and returns each hard-line as-is, so callers can pass a
     #   stale viewport width without crashing.
-    # @return [Array<StyledString>] one entry per physical (output) line.
+    # @return [Array<StyledString>] one entry per output row.
     #   An empty receiver returns `[]`.
     def wrap(width)
       return [] if empty?
 
-      hard_lines = lines
-      return hard_lines if width.nil? || width <= 0
+      input_lines = lines
+      return input_lines if width.nil? || width <= 0
 
       result = []
-      hard_lines.each { |hl| result.concat(wrap_one(hl, width)) }
+      input_lines.each { |line| result.concat(wrap_one(line, width)) }
       result
     end
 
@@ -630,6 +630,46 @@ module Tuile
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(fg: fg)) })
     end
 
+    # Returns a new {StyledString} with `bold` applied to every span, preserving
+    # each span's text and other style attributes (`fg`, `bg`, `italic`,
+    # `underline`, `strikethrough`). The bold-attribute counterpart of
+    # {#with_bg} / {#with_fg}: it emphasizes a whole run of app-authored,
+    # possibly multi-span content — a widget marking one caption out of several
+    # as selected, where the caption may already carry its own colors.
+    #
+    # There is deliberately no `under_bold` (the fill-unset counterpart
+    # {#under_bg} provides for backgrounds): a background is inherited down the
+    # component tree, so a span with none has a meaningful "unset" state to
+    # fill, while `bold` is a plain per-span attribute that is either on or
+    # off. Pass `bold: false` to clear it.
+    #
+    # @param bold [Boolean] whether the spans should be bold.
+    # @return [StyledString]
+    def with_bold(bold: true)
+      self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bold:)) })
+    end
+
+    # Returns a new {StyledString} with `underline` applied to every span,
+    # preserving each span's text and other style attributes (`fg`, `bg`,
+    # `bold`, `italic`, `strikethrough`). Slice and rejoin to underline *part*
+    # of a string, which is what a one-character cue needs:
+    #
+    #   cap = StyledString.parse("File")
+    #   cap.slice(0, 1).with_underline + cap.slice(1, cap.display_width - 1)
+    #   # => "File" with the F underlined — a menu mnemonic
+    #
+    # Note {#slice} counts **columns**, not characters, so a caption with a
+    # wide glyph before the cue needs the prefix measured rather than counted.
+    #
+    # There is deliberately no `under_underline`, for the reason {#with_bold}
+    # spells out. Pass `underline: false` to clear it.
+    #
+    # @param underline [Boolean] whether the spans should be underlined.
+    # @return [StyledString]
+    def with_underline(underline: true)
+      self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(underline:)) })
+    end
+
     # @return [String]
     def inspect
       "#<#{self.class.name} #{to_s.inspect}>"
@@ -717,17 +757,17 @@ module Tuile
       self.class.new(out)
     end
 
-    # @param hard_line [StyledString] one hard-broken line — no embedded `"\n"`.
+    # @param line [StyledString] one line — no embedded `"\n"`.
     # @param width [Integer]
     # @return [Array<StyledString>]
-    def wrap_one(hard_line, width)
-      return [hard_line] if hard_line.empty?
+    def wrap_one(line, width)
+      return [line] if line.empty?
 
       result = []
       line_glyphs = []
       line_w = 0
 
-      tokenize_for_wrap(hard_line).each do |type, glyphs, w|
+      tokenize_for_wrap(line).each do |type, glyphs, w|
         if type == :space
           if line_w.zero? && (!result.empty? || w > width)
             # Nothing to emit: a continuation's leading run was consumed by the
@@ -763,18 +803,18 @@ module Tuile
     # a cluster is the unit a terminal draws, so measuring its parts separately
     # would both mis-total an emoji sequence and let a wrap break a letter away
     # from its combining mark.
-    # @param hard_line [StyledString]
+    # @param line [StyledString]
     # @return [Array<Array>] tokens shaped `[type, glyphs, w]` where `type` is
     #   `:space` or `:word`, `glyphs` is an `Array<[String, Style, Integer]>`
     #   (grapheme cluster, style, display width), and `w` is the token's total
     #   width.
-    def tokenize_for_wrap(hard_line)
+    def tokenize_for_wrap(line)
       tokens = []
       current_glyphs = []
       current_w = 0
       current_type = nil
 
-      each_glyph_with_style(hard_line) do |g, s|
+      each_glyph_with_style(line) do |g, s|
         type = [" ", "\t"].include?(g) ? :space : :word
         gw = Buffer.display_width(g)
         if current_type && current_type != type

data/lib/tuile/version.rb

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

data/lib/tuile/vertical_scroll_bar.rb

@@ -18,20 +18,20 @@ module Tuile
 
     # @param height [Integer] number of rows in the scrollbar (== viewport
     #   height).
-    # @param line_count [Integer] total number of content lines.
-    # @param top_line [Integer] index of the first visible content line.
-    def initialize(height, line_count:, top_line:)
+    # @param row_count [Integer] total number of content rows.
+    # @param scroll_top_row [Integer] index of the first visible content row.
+    def initialize(height, row_count:, scroll_top_row:)
       @height = height
 
       return unless height >= 1
 
-      if line_count <= height
+      if row_count <= height
         @handle_height = height
         @handle_start  = 0
         @handle_end    = height - 1
       else
-        @handle_height = [(height * height / line_count.to_f).ceil, 1].max
-        @handle_start  = (height * top_line / line_count.to_f).floor
+        @handle_height = [(height * height / row_count.to_f).ceil, 1].max
+        @handle_start  = (height * scroll_top_row / row_count.to_f).floor
         @handle_end    = @handle_start + @handle_height - 1
       end
     end