tuile 0.1.0 → 0.3.0

data/lib/tuile/component/text_view.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A read-only viewer for prose: chunks of formatted text that scroll
+    # vertically. Shape-wise a hybrid between {Label} (string-shaped content
+    # via {#text=}) and {List} (scroll keys, optional scrollbar, auto-scroll).
+    #
+    # Text is modeled as a {StyledString}: embedded `\n` are hard line breaks,
+    # lines wider than the viewport are word-wrapped via {StyledString#wrap}
+    # (style spans are preserved across wrap boundaries — unlike the older
+    # ANSI-as-bytes wrapping, color does *not* get dropped on continuation
+    # rows). {#text=} accepts a {String} (parsed via {StyledString.parse},
+    # so embedded ANSI is honored) or a {StyledString} directly; {#text}
+    # always returns the {StyledString}. Use {#append} for incremental "log
+    # line" style updates; turn on {#auto_scroll} to keep the latest content
+    # in view.
+    #
+    # TextView is meant to be the content of a {Window} — focus indication and
+    # keyboard-hint surfacing rely on the surrounding window chrome.
+    class TextView < Component
+      def initialize
+        super
+        # `@hard_lines` is the logical model — one entry per `\n`-delimited
+        # line of the original text, width-independent. `@physical_lines` is
+        # the rendered view — each hard line word-wrapped to `wrap_width`
+        # and padded with trailing blanks, so painting a row is a lookup.
+        # Resizing rebuilds `@physical_lines` from `@hard_lines`; `#append`
+        # extends both.
+        @hard_lines = []
+        @physical_lines = []
+        @text = StyledString::EMPTY
+        @content_size = Size::ZERO
+        @blank_line = StyledString::EMPTY
+        @top_line = 0
+        @auto_scroll = false
+        @scrollbar_visibility = :gone
+      end
+
+      # @return [StyledString] the current text. Defaults to an empty
+      #   {StyledString}. Internally the text is stored as an array of hard
+      #   lines so {#append} can stay O(appended) instead of re-scanning the
+      #   whole buffer; the joined {StyledString} returned here is
+      #   reconstructed on first read after a mutation and cached, so
+      #   repeated reads are O(1) but the first read after {#append} pays
+      #   O(total spans).
+      def text
+        @text ||= build_text
+      end
+
+      # @return [Integer] index of the first visible physical line.
+      attr_reader :top_line
+
+      # @return [Symbol] `:gone` or `:visible`.
+      attr_reader :scrollbar_visibility
+
+      # @return [Boolean] if true, mutating the text scrolls the viewport so
+      #   the last line stays in view. Default `false`.
+      attr_reader :auto_scroll
+
+      # Replaces the text. Embedded `\n` characters become hard line breaks.
+      # A `String` is parsed via {StyledString.parse} (so embedded ANSI is
+      # honored); a `StyledString` is used as-is; `nil` is coerced to an
+      # empty {StyledString}.
+      # @param value [String, StyledString, nil]
+      # @return [void]
+      def text=(value)
+        new_text = StyledString.parse(value)
+        return if text == new_text
+
+        @text = new_text
+        @hard_lines = new_text.empty? ? [] : new_text.lines
+        @content_size = compute_content_size
+        rewrap
+        update_top_line_if_auto_scroll
+        invalidate
+      end
+
+      # Appends `str` as a new physical line. If the current text is empty,
+      # behaves like `text = str`; otherwise prepends a newline so the new
+      # content lands on a fresh line. Accepts the same input forms as
+      # {#text=}.
+      #
+      # Cost is O(appended) rather than O(total) — the existing wrapped
+      # buffer is reused, only the new hard line(s) are wrapped and padded,
+      # and `@content_size` is updated incrementally. The cached
+      # {#text} is invalidated and rebuilt on demand.
+      # @param str [String, StyledString, nil]
+      # @return [void]
+      def append(str)
+        screen.check_locked
+        appended = StyledString.parse(str)
+        if @hard_lines.empty?
+          self.text = appended
+          return
+        end
+
+        new_hard_lines = appended.lines
+        @text = nil
+        @hard_lines.concat(new_hard_lines)
+        new_width = new_hard_lines.map(&:display_width).max || 0
+        @content_size = Size.new(
+          [@content_size.width, new_width].max,
+          @content_size.height + new_hard_lines.size
+        )
+        width = wrap_width
+        new_hard_lines.each { |hl| append_physical_lines(hl, width) }
+        update_top_line_if_auto_scroll
+        invalidate
+      end
+
+      # Clears the text. Equivalent to `text = ""`.
+      # @return [void]
+      def clear
+        self.text = StyledString::EMPTY
+      end
+
+      # @param new_top_line [Integer] 0 or greater. Not clamped against the
+      #   number of lines (matches {List#top_line=}).
+      # @return [void]
+      def top_line=(new_top_line)
+        raise TypeError, "expected Integer, got #{new_top_line.inspect}" unless new_top_line.is_a? Integer
+        raise ArgumentError, "top_line must not be negative, got #{new_top_line}" if new_top_line.negative?
+        return if @top_line == new_top_line
+
+        @top_line = new_top_line
+        invalidate
+      end
+
+      # @param value [Symbol] `:gone` or `:visible`.
+      # @return [void]
+      def scrollbar_visibility=(value)
+        raise ArgumentError, "expected :gone or :visible, got #{value.inspect}" unless %i[gone visible].include?(value)
+        return if @scrollbar_visibility == value
+
+        @scrollbar_visibility = value
+        rewrap
+        invalidate
+      end
+
+      # Sets `auto_scroll`. If true, immediately scrolls to the bottom.
+      # @param value [Boolean]
+      # @return [void]
+      def auto_scroll=(value)
+        @auto_scroll = value ? true : false
+        update_top_line_if_auto_scroll
+      end
+
+      def focusable? = true
+
+      def tab_stop? = true
+
+      # @return [Size] longest hard-line's display width × number of hard
+      #   lines. Reported on the *unwrapped* text — wrap-aware sizing would
+      #   be circular (width depends on width). Empty text returns
+      #   `Size.new(0, 0)`. Maintained incrementally by {#text=} and
+      #   {#append}, so reads are O(1).
+      attr_reader :content_size
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless active?
+        return true if super
+
+        case key
+        when *Keys::DOWN_ARROWS then move_top_line_by(1)
+        when *Keys::UP_ARROWS   then move_top_line_by(-1)
+        when Keys::PAGE_DOWN    then move_top_line_by(viewport_lines)
+        when Keys::PAGE_UP      then move_top_line_by(-viewport_lines)
+        when Keys::CTRL_D       then move_top_line_by(viewport_lines / 2)
+        when Keys::CTRL_U       then move_top_line_by(-viewport_lines / 2)
+        when *Keys::HOMES, "g"  then move_top_line_to(0)
+        when *Keys::ENDS_, "G"  then move_top_line_to(top_line_max)
+        else return false
+        end
+        true
+      end
+
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        case event.button
+        when :scroll_down then move_top_line_by(4)
+        when :scroll_up   then move_top_line_by(-4)
+        end
+      end
+
+      # Paints the text into {#rect}.
+      #
+      # Skips the {Component#repaint} default's auto-clear: every row is
+      # painted explicitly (with padded blanks past the last line), so the
+      # "fully draw over your rect" contract is met without an upfront wipe.
+      # @return [void]
+      def repaint
+        return if rect.empty?
+
+        scrollbar = if scrollbar_visible?
+                      VerticalScrollBar.new(rect.height, line_count: @physical_lines.size, top_line: @top_line)
+                    end
+        (0...rect.height).each do |row|
+          line = paintable_line(row + @top_line, row, scrollbar)
+          screen.print TTY::Cursor.move_to(rect.left, rect.top + row), line
+        end
+      end
+
+      protected
+
+      # Rewraps the text on width changes. Wrap width depends on
+      # {#rect}`.width` and the scrollbar gutter, both of which trigger
+      # this hook.
+      # @return [void]
+      def on_width_changed
+        super
+        rewrap
+      end
+
+      private
+
+      # @return [Integer] number of visible lines.
+      def viewport_lines = rect.height
+
+      # @return [Integer] the max value of {#top_line} for scroll-key clamping.
+      def top_line_max = (@physical_lines.size - viewport_lines).clamp(0, nil)
+
+      # Recomputes {@physical_lines} for the current text and wrap width,
+      # pre-padding every line to `wrap_width` so {#paintable_line} is just
+      # a lookup + optional scrollbar-char append at paint time (and the
+      # rendered ANSI is cached on each line via {StyledString#to_ansi}'s
+      # memoization, so re-painting on scroll is near-free). Clamps
+      # {@top_line} if the new line count puts it out of range.
+      # @return [void]
+      def rewrap
+        width = wrap_width
+        @blank_line = pad_to(StyledString::EMPTY, width)
+        @physical_lines = []
+        @hard_lines.each { |hl| append_physical_lines(hl, width) }
+        @top_line = top_line_max if @top_line > top_line_max
+      end
+
+      # Wraps `hard_line` at `width` and appends the padded physical lines
+      # to {@physical_lines}. Empty hard lines (e.g. from a `"\n\n"` run)
+      # and degenerate `width <= 0` both emit a single {@blank_line} row,
+      # matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
+      # would have produced for those cases.
+      # @param hard_line [StyledString] one hard-broken line (no embedded `"\n"`).
+      # @param width [Integer]
+      # @return [void]
+      def append_physical_lines(hard_line, width)
+        if hard_line.empty? || width <= 0
+          @physical_lines << @blank_line
+        else
+          hard_line.wrap(width).each { |line| @physical_lines << pad_to(line, width) }
+        end
+      end
+
+      # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
+      # default-styled `"\n"` between hard lines. Called from the {#text}
+      # reader when the cache is cold. Cost is O(total spans).
+      # @return [StyledString]
+      def build_text
+        return StyledString::EMPTY if @hard_lines.empty?
+        return @hard_lines.first if @hard_lines.size == 1
+
+        newline = StyledString::Span.new(text: "\n", style: StyledString::Style::DEFAULT)
+        spans = []
+        @hard_lines.each_with_index do |hl, i|
+          spans << newline if i.positive?
+          spans.concat(hl.spans)
+        end
+        StyledString.new(spans)
+      end
+
+      # @return [Size] {#content_size} computed from {@hard_lines}.
+      def compute_content_size
+        return Size::ZERO if @hard_lines.empty?
+
+        Size.new(@hard_lines.map(&:display_width).max || 0, @hard_lines.size)
+      end
+
+      # @return [Integer] column width available for wrapped text — viewport
+      #   width minus the scrollbar gutter (when visible). `0` when {#rect}'s
+      #   width is non-positive, which yields a degenerate "no wrap" result.
+      def wrap_width
+        return 0 if rect.width <= 0
+
+        rect.width - (scrollbar_visible? ? 1 : 0)
+      end
+
+      # @param delta [Integer] negative scrolls up, positive scrolls down.
+      # @return [void]
+      def move_top_line_by(delta)
+        move_top_line_to(@top_line + delta)
+      end
+
+      # @param target [Integer] desired top line; clamped to `[0, top_line_max]`.
+      # @return [void]
+      def move_top_line_to(target)
+        clamped = target.clamp(0, top_line_max)
+        self.top_line = clamped unless @top_line == clamped
+      end
+
+      # @return [void]
+      def update_top_line_if_auto_scroll
+        return unless @auto_scroll
+
+        target = (@physical_lines.size - viewport_lines).clamp(0, nil)
+        self.top_line = target if @top_line != target
+      end
+
+      # @return [Boolean]
+      def scrollbar_visible?
+        return false if rect.empty?
+
+        @scrollbar_visibility == :visible
+      end
+
+      # Pads `line` with trailing default-styled spaces out to `width` display
+      # columns. Callers rely on {StyledString#wrap} having already
+      # constrained the line to `<= width`, so no truncation is performed.
+      # `width <= 0` returns {StyledString::EMPTY} to handle the degenerate
+      # `wrap_width == 0` case (rect.width == 1 with scrollbar).
+      # @param line [StyledString]
+      # @param width [Integer]
+      # @return [StyledString]
+      def pad_to(line, width)
+        return StyledString::EMPTY if width <= 0
+
+        diff = width - line.display_width
+        return line if diff <= 0
+
+        line + StyledString.plain(" " * diff)
+      end
+
+      # @param index [Integer] 0-based index into `@physical_lines`.
+      # @param row_in_viewport [Integer] 0-based row within the viewport.
+      # @param scrollbar [VerticalScrollBar, nil]
+      # @return [String] paintable ANSI-encoded line exactly `rect.width`
+      #   columns wide. Body lines come pre-padded from {#rewrap}, so this
+      #   reduces to a memoized {StyledString#to_ansi} read plus an
+      #   ASCII-string concat of the scrollbar glyph when one is present.
+      def paintable_line(index, row_in_viewport, scrollbar)
+        line = @physical_lines[index] || @blank_line
+        return line.to_ansi unless scrollbar
+
+        line.to_ansi + scrollbar.scrollbar_char(row_in_viewport)
+      end
+    end
+  end
+end

data/lib/tuile/component/window.rb

@@ -90,9 +90,9 @@ module Tuile
       # @param value [Boolean]
       # @return [void]
       def scrollbar=(value)
-        unless content.is_a?(Component::List)
+        unless content.respond_to?(:scrollbar_visibility=)
           raise Tuile::Error,
-                "scrollbar= requires a Component::List as content, got #{content.inspect}"
+                "scrollbar= requires a content component that supports scrollbar_visibility=, got #{content.inspect}"
         end
 
         content.scrollbar_visibility = value ? :visible : :gone
@@ -132,13 +132,21 @@ module Tuile
       end
 
       # Fully repaints the window: both frame and contents.
+      #
+      # Window deliberately paints over its entire rect (border around the
+      # edge, content/footer over the interior), so we don't need the
+      # {Component#repaint} default's auto-clear — but we do still want its
+      # "re-invalidate children" effect, since the border overpaints
+      # whatever the content/footer drew on the perimeter. Calling super
+      # handles both: the auto-clear is harmless (we re-paint over it), and
+      # the invalidation queues content + footer for repaint in the same
+      # cycle.
       # @return [void]
       def repaint
+        return unless visible?
+
         super
         repaint_border
-        # Border paints over content: invalidate the content to have it
-        # repainted.
-        content&.invalidate
       end
 
       # @param key [String, nil]

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