tuile 0.1.0 → 0.2.0

data/lib/tuile/component.rb

@@ -44,14 +44,36 @@ module Tuile
       screen.focused = self
     end
 
-    # Repaints the component. Default implementation does nothing.
+    # Repaints the component.
     #
-    # The component must fully draw over {#rect}, and must not draw outside of
-    # {#rect}.
+    # The default does the bookkeeping that almost every component would
+    # otherwise have to remember: it clears the background and re-invalidates
+    # any direct children whose rects leave gaps in {#rect}. Concretely:
     #
-    # Tip: use {#clear_background} to clear component background before painting.
+    # - Leaf (no children): always clears, so subclasses can paint their
+    #   content directly without an explicit `clear_background` call.
+    # - Container with children that fully tile {#rect}: skipped — the
+    #   children themselves will repaint and cover everything.
+    # - Container with gappy children (e.g. a form layout where widgets
+    #   don't tile): clears, then invalidates the children so they re-paint
+    #   on top of the cleared background. This is what makes mixed
+    #   field/button forms safe without each container learning a custom
+    #   damage-tracking pass.
+    #
+    # Subclasses that paint their entire rect themselves (e.g. {Window}'s
+    # border draws over the area the default would clear; {Component::List}
+    # explicitly paints every row) may skip super and take full
+    # responsibility for {#rect}. Everything else should call super.
+    #
+    # A component must not draw outside of {#rect}.
     # @return [void]
-    def repaint; end
+    def repaint
+      return if rect.empty? || rect.left.negative? || rect.top.negative?
+      return if children.any? && children_tile_rect?
+
+      clear_background
+      children.each { |c| screen.invalidate(c) }
+    end
 
     # Called when a character is pressed on the keyboard.
     #
@@ -123,9 +145,22 @@ module Tuile
     # Independent from {#active?}: every component carries the active flag, but
     # only focusable ones can become a focus target that puts themselves and
     # their ancestors on the active chain.
+    #
+    # See also {#tab_stop?}: focusable controls _can_ receive focus (via click
+    # or programmatic assignment), but only tab stops participate in Tab /
+    # Shift+Tab cycling. Containers like {Window} and {Popup} are focusable
+    # (so a click on chrome lands focus) but are not tab stops.
     # @return [Boolean] true if this component can be focused.
     def focusable? = false
 
+    # Whether this component participates in Tab / Shift+Tab focus cycling.
+    # `false` by default. Only true on components that accept direct user
+    # input (e.g. {TextField}, {List}, {Component::Button}). Implies
+    # {#focusable?} — Screen will skip non-focusable tab stops, but in
+    # practice every override should keep the two consistent.
+    # @return [Boolean] true if Tab / Shift+Tab should land on this component.
+    def tab_stop? = false
+
     # @return [Component, nil] the parent component or nil if the component has
     #   no parent.
     attr_reader :parent
@@ -221,6 +256,19 @@ module Tuile
       screen.invalidate(self)
     end
 
+    # Whether direct children fully tile {#rect}. Used by the default
+    # {#repaint} to decide whether the framework needs to wipe gaps.
+    #
+    # Approximated by area: sum of (non-empty) child areas vs the parent's
+    # area. Cheap, and correct as long as siblings don't overlap each other
+    # — which Tuile already requires (no clipping in the tiled tree).
+    # Children with empty rects contribute zero, since they paint nothing.
+    # @return [Boolean]
+    def children_tile_rect?
+      total = children.sum { |c| c.rect.empty? ? 0 : c.rect.width * c.rect.height }
+      total >= rect.width * rect.height
+    end
+
     # Clears the background: prints spaces into all characters occupied by the
     # component's rect.
     # @return [void]

data/lib/tuile/event_queue.rb

@@ -70,7 +70,20 @@ module Tuile
           event_loop(&)
         ensure
           Signal.trap("WINCH", "SYSTEM_DEFAULT")
-          @key_thread&.kill
+          if @key_thread
+            # Kill returns immediately, but the key thread is typically
+            # blocked inside $stdin.getch with a termios snapshot saved in
+            # io-console's C-level ensure. If we let it run to completion
+            # *after* the outer $stdin.raw block has exited (e.g. when an
+            # exception is escaping run_event_loop), the late tcsetattr
+            # restores raw mode and leaves the terminal with ONLCR off —
+            # the stack trace then prints as one un-wrapped soft line.
+            # Joining here forces the restore to happen while we're still
+            # nested inside $stdin.raw, so raw's own restoration is the
+            # final write and the terminal lands in cooked mode.
+            @key_thread.kill
+            @key_thread.join
+          end
           @queue.clear
         end
       end

data/lib/tuile/keys.rb

@@ -18,17 +18,31 @@ module Tuile
     # @return [String]
     RIGHT_ARROW = "\e[C"
     # @return [String]
+    CTRL_LEFT_ARROW = "\e[1;5D"
+    # @return [String]
+    CTRL_RIGHT_ARROW = "\e[1;5C"
+    # @return [String]
     ESC = "\e"
     # @return [String]
     HOME = "\e[H"
     # @return [String]
     END_ = "\e[F"
+    # Home-key sequences. xterm-style (`HOME`) is the modern default, but the
+    # Linux console, rxvt, and tmux/screen in their default configuration emit
+    # the VT220-style `\e[1~` instead. Components that handle Home should
+    # match against this array so users see consistent behavior regardless of
+    # which sequence their terminal emits.
+    # @return [Array<String>]
+    HOMES = [HOME, "\e[1~"].freeze
+    # End-key sequences. See {HOMES} for why two are recognized.
+    # @return [Array<String>]
+    ENDS_ = [END_, "\e[4~"].freeze
     # @return [String]
     PAGE_UP = "\e[5~"
     # @return [String]
     PAGE_DOWN = "\e[6~"
     # @return [String]
-    BACKSPACE = "\u007f"
+    BACKSPACE = ""
     # @return [String]
     DELETE = "\e[3~"
     # @return [String]
@@ -36,11 +50,17 @@ module Tuile
     # @return [Array<String>]
     BACKSPACES = [BACKSPACE, CTRL_H].freeze
     # @return [String]
-    CTRL_U = "\u0015"
+    CTRL_U = ""
+    # @return [String]
+    CTRL_D = ""
+    # @return [String]
+    ENTER = "
     # @return [String]
-    CTRL_D = "\u0004"
+    TAB = "\t"
+    # The terminal sequence emitted by Shift+Tab in xterm-style terminals
+    # (CSI Z). Used by {Screen} for reverse focus traversal.
     # @return [String]
-    ENTER = "\u000d"
+    SHIFT_TAB = "\e[Z"
 
     # 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

data/lib/tuile/screen.rb

@@ -186,6 +186,17 @@ module Tuile
       $stdin.echo = true
     end
 
+    # Advances focus to the next {Component#tab_stop?} in tree order, wrapping
+    # around. Scope is the topmost popup if one is open, otherwise {#content}
+    # — this keeps Tab confined inside a modal popup. No-op (returns false) if
+    # the modal scope has no tab stops or no content at all.
+    # @return [Boolean] true if focus moved.
+    def focus_next = cycle_focus(forward: true)
+
+    # Mirror of {#focus_next} that walks backwards through the tab order.
+    # @return [Boolean] true if focus moved.
+    def focus_previous = cycle_focus(forward: false)
+
     # @return [Component, nil] current active tiled component.
     def active_window
       check_locked
@@ -235,11 +246,31 @@ module Tuile
       @@instance&.close
     end
 
-    # Prints given strings.
+    # Prints given strings. While {#repaint} is running, writes are
+    # accumulated into a frame buffer and flushed to the terminal as a
+    # single `$stdout.write` at the end of the cycle. This stops the
+    # emulator from rendering half-finished frames (e.g. a layout's
+    # clear-background pass before its children have re-painted), which
+    # was visible as a brief flicker when the auto-clear path triggers.
+    #
+    # Outside repaint, writes go straight to stdout. We deliberately
+    # don't raise on a "print outside repaint" — that would be a useful
+    # guardrail against components painting outside the repaint loop,
+    # but it'd force terminal-housekeeping writes (`Screen#clear`,
+    # mouse-tracking start/stop, cursor-show on teardown) to bypass
+    # this method entirely and write directly to `$stdout`. {FakeScreen}
+    # overrides `print` to capture every byte into its `@prints` array,
+    # and tests that exercise `run_event_loop` against a real {Screen}
+    # would otherwise leak escape sequences to the test runner's stdout.
+    # Keeping `print` as the single sink preserves that override seam.
     # @param args [String] stuff to print.
     # @return [void]
     def print(*args)
-      Kernel.print(*args)
+      if @frame_buffer
+        args.each { |s| @frame_buffer << s.to_s }
+      else
+        Kernel.print(*args)
+      end
     end
 
     # Repaints the screen; tries to be as effective as possible, by only
@@ -255,43 +286,56 @@ module Tuile
       # simple and very fast in common cases.
 
       did_paint = false
-      until @invalidated.empty?
-        did_paint = true
-        popups = @pane.popups
-
-        # Partition invalidated components into tiled vs popup-tree. Sorting
-        # by depth across the whole tree would interleave them: a tiled
-        # grandchild (depth 3) sorts after a popup's content (depth 2) and
-        # overdraws it.
-        popup_tree = Set.new
-        popups.each { |p| p.on_tree { popup_tree << it } }
-        tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(it) }
-
-        # Within the tiled tree, paint parents before children.
-        tiled.sort_by!(&:depth)
-
-        repaint = if tiled.empty?
-                    # Only popups need repaint — paint just their invalidated
-                    # components in depth order.
-                    popup_invalidated.sort_by(&:depth)
-                  else
-                    # Tiled components may overdraw popups; repaint each open
-                    # popup's full subtree on top, in stacking order
-                    # (parent-before-child within each popup).
-                    tiled + popups.flat_map { |p| collect_subtree(p) }
-                  end
-
-        @repainting = repaint.to_set
-        @invalidated.clear
-
-        # Don't call {#clear} before repaint — causes flickering, and only
-        # needed when @content doesn't cover the entire screen.
-        repaint.each(&:repaint)
-
-        # Repaint done, mark all components as up-to-date.
-        @repainting.clear
+      @frame_buffer = +""
+      begin
+        until @invalidated.empty?
+          did_paint = true
+          popups = @pane.popups
+
+          # Partition invalidated components into tiled vs popup-tree. Sorting
+          # by depth across the whole tree would interleave them: a tiled
+          # grandchild (depth 3) sorts after a popup's content (depth 2) and
+          # overdraws it.
+          popup_tree = Set.new
+          popups.each { |p| p.on_tree { popup_tree << it } }
+          tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(it) }
+
+          # Within the tiled tree, paint parents before children.
+          tiled.sort_by!(&:depth)
+
+          repaint = if tiled.empty?
+                      # Only popups need repaint — paint just their invalidated
+                      # components in depth order.
+                      popup_invalidated.sort_by(&:depth)
+                    else
+                      # Tiled components may overdraw popups; repaint each open
+                      # popup's full subtree on top, in stacking order
+                      # (parent-before-child within each popup).
+                      tiled + popups.flat_map { |p| collect_subtree(p) }
+                    end
+
+          @repainting = repaint.to_set
+          @invalidated.clear
+
+          # Don't call {#clear} before repaint — causes flickering, and only
+          # needed when @content doesn't cover the entire screen.
+          repaint.each(&:repaint)
+
+          # Repaint done, mark all components as up-to-date.
+          @repainting.clear
+        end
+        position_cursor if did_paint
+        unless @frame_buffer.empty?
+          $stdout.write(@frame_buffer)
+          $stdout.flush
+        end
+      ensure
+        # Always release the frame buffer, even on exception, so any
+        # subsequent {#print} call (e.g. teardown emits during crash unwind)
+        # reaches stdout instead of being swallowed by a stranded buffer.
+        # The partial frame we hold here is incoherent — discard it.
+        @frame_buffer = nil
       end
-      position_cursor if did_paint
     end
 
     # Returns the absolute screen coordinates where the hardware cursor should
@@ -303,6 +347,34 @@ module Tuile
 
     private
 
+    # Walks the current modal scope in pre-order, collects tab stops, and
+    # advances focus by one (wrapping). When the focused component isn't in
+    # the tab order (e.g. focus is parked on a popup/window chrome with no
+    # interactable widgets), Tab goes to the first stop and Shift+Tab to the
+    # last.
+    # @param forward [Boolean]
+    # @return [Boolean] true if focus moved.
+    def cycle_focus(forward:)
+      check_locked
+      scope = @pane.popups.last || @pane.content
+      return false if scope.nil?
+
+      stops = []
+      scope.on_tree { |c| stops << c if c.tab_stop? }
+      return false if stops.empty?
+
+      idx = @focused.nil? ? nil : stops.index(@focused)
+      target = if idx.nil?
+                 forward ? stops.first : stops.last
+               else
+                 stops[(idx + (forward ? 1 : -1)) % stops.size]
+               end
+      return false if target.equal?(@focused)
+
+      self.focused = target
+      true
+    end
+
     # Collects a component and all its descendants in tree order
     # (parent before children).
     # @param component [Component]
@@ -344,9 +416,25 @@ 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.
     # @param key [String]
     # @return [Boolean] true if the key was handled by some window.
-    def handle_key(key) = @pane.handle_key(key)
+    def handle_key(key)
+      case key
+      when Keys::TAB
+        focus_next
+        true
+      when Keys::SHIFT_TAB
+        focus_previous
+        true
+      else
+        @pane.handle_key(key)
+      end
+    end
 
     # Finds target window and calls {Component::Window#handle_mouse}.
     # @param event [MouseEvent]

data/lib/tuile/screen_pane.rb

@@ -140,16 +140,22 @@ module Tuile
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
-      clicked = @popups.rfind { it.rect.contains?(event.point) }
+      clicked = @popups.reverse_each.find { it.rect.contains?(event.point) }
       clicked = @content if clicked.nil? && @popups.empty?
       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 now-topmost popup, then to the prior focus
-    # snapshotted when this popup was opened (if still attached), then to
-    # content, then nil.
+    # Instead, route focus to the first interactable widget in the now-topmost
+    # 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.
+    #
+    # "First interactable widget" = first {Component#tab_stop?} in pre-order;
+    # if a scope has no tab stops at all (a borderless ESC-to-close popup, or
+    # tiled content made entirely of {Label}s), we focus the scope's root so
+    # `q`/ESC still has somewhere to dispatch from.
     # @param child [Component]
     # @return [void]
     def on_child_removed(child)
@@ -161,14 +167,30 @@ module Tuile
       cursor = f
       while cursor
         if cursor == child
-          fallback = @popups.last
-          fallback ||= @removing_popup_prior if @removing_popup_prior&.attached?
-          fallback ||= @content
+          fallback = first_tab_stop_or_root(@popups.last)
+          if fallback.nil? && @removing_popup_prior&.attached? && @removing_popup_prior.focusable?
+            fallback = @removing_popup_prior
+          end
+          fallback ||= first_tab_stop_or_root(@content)
           screen.focused = fallback
           return
         end
         cursor = cursor.parent
       end
     end
+
+    private
+
+    # 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`.
+    # @param root [Component, nil]
+    # @return [Component, nil]
+    def first_tab_stop_or_root(root)
+      return nil if root.nil?
+
+      root.on_tree { |c| return c if c.tab_stop? }
+      root
+    end
   end
 end

data/lib/tuile/truncate.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Truncates a string to a given column width, preserving ANSI escape
+  # sequences and accounting for Unicode display width. Truncated output is
+  # suffixed with an ellipsis (`…`).
+  #
+  # Extracted from `strings-truncation` 0.1.0 (MIT, Piotr Murach) — only the
+  # default end-position, default-omission, no-separator path Tuile uses.
+  module Truncate
+    # @return [Regexp]
+    ANSI_REGEXP = /(\[)?\033(\[)?[;?\d]*[\dA-Za-z]([\];])?/
+    private_constant :ANSI_REGEXP
+
+    # @return [String]
+    RESET = "\e[0m"
+    private_constant :RESET
+
+    # @return [Regexp]
+    RESET_REGEXP = /#{Regexp.escape(RESET)}/
+    private_constant :RESET_REGEXP
+
+    # @return [Regexp]
+    END_REGEXP = /\A(#{ANSI_REGEXP})*\z/
+    private_constant :END_REGEXP
+
+    # @return [String]
+    OMISSION = "…"
+    private_constant :OMISSION
+
+    # @return [Integer]
+    OMISSION_WIDTH = 1
+    private_constant :OMISSION_WIDTH
+
+    module_function
+
+    # Truncate `text` to at most `length` display columns. ANSI escape
+    # sequences pass through without consuming budget; when characters are
+    # dropped, an ellipsis (`…`) is appended (and counts toward `length`).
+    #
+    # @param text [String]
+    # @param length [Integer, nil] target column width. A `nil` returns
+    #   `text` unchanged.
+    # @return [String]
+    def truncate(text, length:)
+      return text if length.nil? || text.bytesize <= length
+      return "" if length.zero?
+
+      budget = length - OMISSION_WIDTH
+      scanner = StringScanner.new(text)
+      out = +""
+      visible = 0
+      ansi_open = false
+      stop = false
+
+      until scanner.eos? || stop
+        if scanner.scan(RESET_REGEXP)
+          unless scanner.eos?
+            out << scanner.matched
+            ansi_open = false
+          end
+        elsif scanner.scan(ANSI_REGEXP)
+          out << scanner.matched
+          ansi_open = true
+        else
+          char = scanner.getch
+          new_visible = visible + Unicode::DisplayWidth.of(char)
+
+          if new_visible <= budget || (scanner.check(END_REGEXP) && new_visible <= length)
+            out << char
+            visible = new_visible
+          else
+            stop = true
+          end
+        end
+      end
+
+      out << RESET if ansi_open
+      out << OMISSION if stop
+      out
+    end
+  end
+end

data/lib/tuile/version.rb

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

data/lib/tuile.rb

@@ -5,7 +5,7 @@ require "io/console"
 require "logger"
 require "rainbow"
 require "singleton"
-require "strings-truncation"
+require "strscan"
 require "tty-cursor"
 require "tty-screen"
 require "unicode/display_width"