tuile 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd5711addbd65a00c8d471204d50973da93ac9be65ba197114ac04c94cace526
-  data.tar.gz: 4505d93153dc96fd439e5d69a7b1506e985fc9094f8428fe092ebc6247d62b8a
+  metadata.gz: 23a6288632a551240d224975faee1f71d477bb1465126d70915950f67c187650
+  data.tar.gz: 33e26892d2a625e85d5d2f2fd058a04080ef12ea38825cb2f9727a346f36c6a2
 SHA512:
-  metadata.gz: 23c69343d8a0cc87143b12cd1a4a9a11862c770debf9c5381cabfcb59b55786f8be143ef362581e0a79bb1dc7f9ce512f47d755f603cb486bf4058b3487d4399
-  data.tar.gz: '0974d322289b63b43bdd498e172f446d7cc56df656645b8e6826fed388154dda4a287110819d305572dbbf1c1ee23011fc4e0cb208f6459d67535e2df5c1d2b1'
+  metadata.gz: 233960b007d8c81281e6726e605ab48e9bdc389399b796a4d9a19314e1be2bfab019a787ddc6ab8b421221010cb9402fdc102737fef085aaa326641b76275eed
+  data.tar.gz: 68b2425566e2a2586d686699df135a4a7fce835b0f2ca5f090204b3b82f6d3b6d7813375f9129e5256eea627be8df72e667694869d4ba475de55221c0db5ae8e

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-20
+
+- Add `Screen#register_global_shortcut` for app-level hotkeys; registered shortcuts surface in the status bar via `hint:`.
+- Add `Keys::CTRL_A..CTRL_Z` constants and `Keys.printable?` (extracted from `TextField`/`TextArea`/`Screen`).
+- Extract `Component::TextInput` as the shared base of `TextField` and `TextArea`; add `#empty?`.
+- `TextField`/`TextArea`: default `on_escape` to clear focus.
+- `Screen#run_event_loop` accepts `capture_mouse:` (default `true`); pass `false` to skip xterm mouse tracking so the terminal's native select-to-copy keeps working.
+- `StyledString`: add `#with_fg`, mirroring `#with_bg`.
+- `Component::TextView`: add `#<<`, `#add_line`, `#empty?`, and `#remove_last_n_lines` for streaming-tail retraction.
+- `MouseEvent`: map buttons 66/67 to `:scroll_left`/`:scroll_right`.
+- `Component::LogWindow`: extract `#log` helper.
+- `Component::List`: skip `auto_scroll` when rect is empty; re-snap on width change; snap cursor to last line on `auto_scroll`.
+- Document `Component#repaint`'s attached-only call contract.
+- Document keyboard input dispatch order and testing (`FakeScreen`, PTY system tests) in the README.
+- **Breaking:** `Component::TextView#append` is now verbatim — chunks are concatenated onto the current last hard line, embedded `\n` becomes hard breaks, no implicit newline is inserted. Designed for streaming use (e.g. an LLM chat window feeding partial messages straight in). Aliased as `<<` for chainability. The old "add a new entry" behavior is now `Component::TextView#add_line`.
+- **Breaking:** `MouseEvent.parse` raises on malformed input instead of silently truncating.
+- Fix: `Component` gates `invalidate` and `repaint` on `attached?`, dropping the negative-rect relic.
+- Fix: `Popup` recomputes size from content on every `#open`.
+- Fix: `Keys.getkey` reads 5 trailing bytes after ESC, not 6.
+- Fix: `Component::List#add_line` rejects `nil`.
+
 ## [0.3.0] - 2026-05-18
 
 - Add `Component::TextView` — read-only scrollable wrapped prose with word wrap, incremental append, and a lazy text reader.

data/README.md

@@ -146,7 +146,7 @@ posts a size event, runs layout, and invalidates the entire tree. Components
 react by reassigning their child rectangles inside `rect=` — do not install
 your own WINCH handler.
 
-### Focus and shortcuts
+### Focus and keyboard input
 
 `screen.focused = component` walks parent pointers up to the root, marks the
 whole chain `active?`, and deactivates everything else. Click-to-focus and
@@ -154,10 +154,86 @@ whole chain `active?`, and deactivates everything else. Click-to-focus and
 returns true, so clicking a `Label` inside a `Window` does not pull focus
 away from the window's content.
 
-`key_shortcut` is matched against the focused component's whole subtree
-*unless* the focused component owns the hardware cursor (e.g. a `TextField`
-the user is typing into) — that suppression is what lets text fields swallow
-printable keys without sibling shortcuts hijacking them.
+When a key arrives, the screen dispatches it in this order — the first
+mechanism that handles it wins:
+
+1. **Tab / Shift+Tab** advance focus through `tab_stop?` components in the
+   current modal scope (the topmost popup if one is open, otherwise the
+   tiled content). They are intercepted at the screen level before anything
+   else sees them, so a focused `TextField` cannot swallow them.
+
+2. **Global shortcuts** registered via `Screen#register_global_shortcut`.
+   These are app-level hotkeys for actions that don't belong to any
+   specific component — opening a log window, toggling help, etc.:
+
+   ```ruby
+   screen.register_global_shortcut(Tuile::Keys::CTRL_L,
+                                   over_popups: true,
+                                   hint: "^L #{Rainbow('log').cadetblue}") do
+     log_popup.open
+   end
+   screen.unregister_global_shortcut(Tuile::Keys::CTRL_L)
+   ```
+
+   Only unprintable keys are accepted (control characters, ESC, BACKSPACE,
+   arrows, F-keys); printable keys raise so they can't hijack typing into
+   a `TextField`. By default, the shortcut is suppressed while any popup
+   is open and the popup receives the key; pass `over_popups: true` to
+   pre-empt the popup.
+
+   Pass `hint:` to surface the shortcut in the status bar. It's a
+   preformatted string the caller fully owns (color it however the rest
+   of your app does). In the tiled case it appears right after `q quit`
+   and before the active window's hint; while a popup is open, only
+   `over_popups: true` hints show up, prepended before the popup's
+   `q Close`. Omit `hint:` to leave the shortcut silent in the status bar.
+
+3. **`Component#key_shortcut`** — a declarative hotkey attached to a
+   component. The framework walks the focused component's subtree for a
+   match and focuses the winner. Good fit for "press F to focus the filter
+   field" or one-key tab pickers. The lookup is suppressed while the
+   focused component owns the hardware cursor (e.g. a `TextField` the user
+   is typing into) so editing isn't interrupted:
+
+   ```ruby
+   filter_field.key_shortcut = "f"
+   ```
+
+4. **`Component#handle_key`** — override this on your own component when
+   it needs to react to keys directly (a list reacting to arrows, a custom
+   widget handling Enter, …). Return `true` to mark the key handled,
+   `false` to let the dispatcher keep walking. Call `super` to keep the
+   default `key_shortcut` subtree lookup; suppress it only when you
+   deliberately want this component to swallow everything:
+
+   ```ruby
+   class Toggle < Tuile::Component
+     def handle_key(key)
+       if key == " "
+         @on = !@on
+         invalidate
+         true
+       else
+         super
+       end
+     end
+   end
+   ```
+
+If nothing handles the key and it's `q` or `ESC`, the event loop exits.
+
+A component can advertise the keys it responds to by overriding
+`keyboard_hint`. The status bar shows the active window's hint alongside
+the global `q quit` prompt; while a popup is open, the popup's own hint
+replaces it, prefixed with `q Close`:
+
+```ruby
+class FilterWindow < Tuile::Component::Window
+  def keyboard_hint
+    "f #{Rainbow('filter').cadetblue}  Enter #{Rainbow('open').cadetblue}"
+  end
+end
+```
 
 ## Components
 
@@ -352,6 +428,62 @@ Tuile.logger = TTY::Logger.new                  # duck-typed, works directly
 Tuile.logger = Logger.new(Tuile::Component::LogWindow::IO.new(window))
 ```
 
+## Testing
+
+Tuile ships with a `Tuile::FakeScreen` that you install in place of the real
+screen for unit tests. It fixes the viewport at 160×50, disables the UI lock,
+collects every string the framework "would have printed" into an array, and
+uses a synchronous `FakeEventQueue` (submitted blocks run inline; posted
+events are discarded). No terminal IO happens, so the TTY running the tests
+is never painted over.
+
+The standard setup is `Screen.fake` / `Screen.close` as a before/after pair —
+this resets the singleton between examples, so state can't leak across
+tests:
+
+```ruby
+require "tuile"
+
+module Tuile
+  describe Component::Label do
+    before { Screen.fake }
+    after  { Screen.close }
+
+    it "renders text into its rect" do
+      label = Component::Label.new
+      label.rect = Rect.new(0, 0, 5, 1)
+      label.text = "hi"
+      label.repaint
+      assert_equal [TTY::Cursor.move_to(0, 0), "hi   "], Screen.instance.prints
+    end
+  end
+end
+```
+
+Key hooks:
+
+- `Screen.instance.prints` — array of strings the screen would have written
+  to the terminal. Assert against it (or `.join`) for repaint output.
+- `Screen.instance.repaint` — drive a repaint synchronously; production code
+  must not call this, but specs use it to flush the invalidated set after a
+  mutation.
+- `Screen.instance.invalidated?(component)` / `invalidated_clear` — verify
+  that a mutation did (or did not) invalidate something. Setting a property
+  to its current value should typically *not* invalidate.
+- `Screen.instance.clear` — drops accumulated `prints` without resetting
+  invalidation.
+
+Because `FakeEventQueue#submit` runs the block immediately on the calling
+thread, code paths that marshal work back via `screen.event_queue.submit { … }`
+just work in tests. Posted events (`#post`) are dropped — if your test needs
+to drive a real event loop, you are in system-test territory.
+
+For end-to-end tests of a runnable script, spawn it in a pseudo-TTY with
+`PTY.spawn`, wait for a known glyph to confirm the first paint landed, send
+a key, and assert the exit status. `spec/examples/hello_world_spec.rb` is the
+canonical template; PTY-based tests are Linux/macOS only since Ruby's stdlib
+`PTY` isn't on Windows.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then,

data/lib/tuile/component/label.rb

@@ -57,7 +57,7 @@ module Tuile
       # wipe.
       # @return [void]
       def repaint
-        return if rect.empty? || rect.left.negative? || rect.top.negative?
+        return if rect.empty?
 
         (0...rect.height).each do |row|
           line = @clipped_lines[row] || @blank_line

data/lib/tuile/component/list.rb

@@ -167,6 +167,7 @@ module Tuile
       # @param line [String, StyledString, #to_s]
       # @return [void]
       def add_line(line)
+        raise ArgumentError, "line is nil" if line.nil?
         add_lines [line]
       end
 
@@ -326,6 +327,16 @@ module Tuile
           def candidate_positions(_line_count)
             []
           end
+
+          # Overridden so all movement funnels — base {Cursor#go_to_last},
+          # {Cursor#go_to_first}, etc., which all call {#go} — become safe
+          # no-ops on a disabled cursor. The instance is frozen, so a default
+          # mutating {#go} would raise.
+          # @param _new_position [Integer]
+          # @return [Boolean] always false.
+          def go(_new_position)
+            false
+          end
         end
 
         # @return [Integer] 0-based line index of the current cursor position.
@@ -384,6 +395,15 @@ module Tuile
           true
         end
 
+        # Moves the cursor to the last reachable position. For base {Cursor},
+        # the last line; {Limited} clamps to the last allowed position; {None}
+        # is a no-op.
+        # @param line_count [Integer] number of lines in the list.
+        # @return [Boolean] true if the position changed.
+        def go_to_last(line_count)
+          go(line_count - 1)
+        end
+
         protected
 
         # @param lines [Integer]
@@ -404,12 +424,6 @@ module Tuile
           go(0)
         end
 
-        # @param line_count [Integer]
-        # @return [Boolean]
-        def go_to_last(line_count)
-          go(line_count - 1)
-        end
-
         # Cursor which can only land on specific allowed lines.
         class Limited < Cursor
           # @param positions [Array<Integer>] allowed positions. Must not be
@@ -442,6 +456,12 @@ module Tuile
             @positions.select { it < line_count }
           end
 
+          # @param _line_count [Integer]
+          # @return [Boolean]
+          def go_to_last(_line_count)
+            go(@positions.last)
+          end
+
           protected
 
           # @param lines [Integer]
@@ -467,12 +487,6 @@ module Tuile
           def go_to_first
             go(@positions.first)
           end
-
-          # @param _line_count [Integer]
-          # @return [Boolean]
-          def go_to_last(_line_count)
-            go(@positions.last)
-          end
         end
       end
 
@@ -480,11 +494,16 @@ module Tuile
 
       # Rebuilds pre-padded lines when the wrap width changes. The wrap width
       # depends on {#rect}`.width` and the scrollbar gutter, both of which
-      # trigger this hook.
+      # trigger this hook. Also re-evaluates {#auto_scroll}: if items were
+      # appended while the rect was empty (e.g. a {Popup}-wrapped list got
+      # `add_line` calls before the popup was opened), the auto-scroll update
+      # was skipped because there was no viewport — re-run it now that there
+      # is one, so the list snaps to the bottom on first paint.
       # @return [void]
       def on_width_changed
         super
         rebuild_padded_lines
+        update_top_line_if_auto_scroll
       end
 
       private
@@ -638,10 +657,20 @@ module Tuile
         invalidate
       end
 
-      # If auto-scrolling, recalculate the top line.
+      # If auto-scrolling, recalculate the top line and snap the cursor to the
+      # last reachable position. Without the cursor snap the viewport gets
+      # yanked back to wherever the cursor sat on the next arrow press,
+      # negating the auto-scroll. Skipped when {#rect} is empty: without a
+      # viewport the "lines minus viewport" formula yields `@lines.size`,
+      # which would leave `top_line` past the last item once a real rect
+      # arrives. {#on_width_changed} re-runs this hook when the rect grows so
+      # the snap-to-bottom intent is preserved.
       # @return [void]
       def update_top_line_if_auto_scroll
         return unless @auto_scroll
+        return if rect.empty?
+
+        notify_cursor_changed if @cursor.go_to_last(@lines.size)
 
         new_top_line = (@lines.size - viewport_lines).clamp(0, nil)
         return unless @top_line != new_top_line

data/lib/tuile/component/log_window.rb

@@ -23,6 +23,16 @@ module Tuile
         self.scrollbar = true
       end
 
+      # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
+      # @param string [String, nil] the line (or multiple lines) to log.
+      # @return [void]
+      def log(string)
+        return if string.nil?
+        screen.event_queue.submit do
+          content.add_line(string)
+        end
+      end
+
       # IO-shaped adapter that forwards each log line to the owning {LogWindow}.
       # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
       # call `output.puts`, e.g. `TTY::Logger`).
@@ -35,17 +45,13 @@ module Tuile
         # @param string [String]
         # @return [void]
         def write(string)
-          @window.screen.event_queue.submit do
-            @window.content.add_line(string.chomp)
-          end
+          @window.log(string.chomp)
         end
 
         # @param string [String]
         # @return [void]
         def puts(string)
-          @window.screen.event_queue.submit do
-            @window.content.add_line(string)
-          end
+          @window.log(string)
         end
 
         # Stdlib `Logger` only treats an object as an IO target when it

data/lib/tuile/component/popup.rb

@@ -30,17 +30,17 @@ module Tuile
       def initialize(content: nil)
         super()
         @content = nil
-        # Off-screen sentinel until the content sets a real size and the popup
-        # is centered on open.
-        @rect = Rect.new(-1, -1, 0, 0)
         self.content = content unless content.nil?
       end
 
       def focusable? = true
 
-      # Mounts this popup on the {Screen}.
+      # Mounts this popup on the {Screen}. Recomputes the popup's size from
+      # the current content first, so reopening a popup whose content has
+      # grown or shrunk while closed picks up the new size.
       # @return [void]
       def open
+        update_rect unless @content.nil?
         screen.add_popup(self)
       end
 
@@ -119,7 +119,7 @@ module Tuile
       def update_rect
         size = @content.content_size.clamp_height(max_height)
         size = size.clamp(Size.new(screen.size.width * 4 / 5, screen.size.height * 4 / 5))
-        self.rect = Rect.new(-1, -1, size.width, size.height)
+        self.rect = Rect.new(0, 0, size.width, size.height)
         center if open?
       end
     end

data/lib/tuile/component/text_area.rb

@@ -18,63 +18,22 @@ module Tuile
     # Currently only {#on_change} is wired; Enter inserts a newline as in any
     # plain `<textarea>` or text editor. A future `on_enter`/`on_submit`
     # callback may opt out of that by consuming Enter instead.
-    class TextArea < Component
+    class TextArea < TextInput
       def initialize
         super
-        @text = +""
-        @caret = 0
         @top_display_row = 0
-        @on_change = nil
+        # Lazy cache of the word-wrapped layout: an
+        # `Array<Hash{Symbol=>Integer}>` whose entries are
+        # `{start: <text-index>, length: <chars>}`, one per display row, built
+        # by {#compute_display_rows}. `nil` means "stale, recompute on next
+        # read". Reset to nil whenever {#text} mutates or the width changes;
+        # see {#on_text_mutated} and {#on_width_changed}.
         @display_rows = nil
       end
 
-      # @return [String] current text contents (may contain embedded `\n`).
-      attr_reader :text
-
-      # @return [Integer] caret index in `0..text.length`.
-      attr_reader :caret
-
       # @return [Integer] index of the topmost display row currently visible.
       attr_reader :top_display_row
 
-      # Optional callback fired whenever {#text} changes. Receives the new text
-      # as a single argument. Not fired by {#caret=} (text unchanged), not
-      # fired by a no-op setter, and not fired by a re-wrap caused by a width
-      # change ({#text} itself is unchanged).
-      # @return [Proc, Method, nil] one-arg callable, or nil.
-      attr_accessor :on_change
-
-      # Sets the text. Caret is clamped to the new text length; vertical scroll
-      # is adjusted to keep the caret visible.
-      # @param new_text [String]
-      def text=(new_text)
-        new_text = new_text.to_s
-        return if @text == new_text
-
-        @text = +new_text
-        @caret = @caret.clamp(0, @text.length)
-        @display_rows = nil
-        adjust_top_display_row
-        invalidate
-        @on_change&.call(@text)
-      end
-
-      # Sets the caret position. Clamped to `0..text.length`; vertical scroll
-      # is adjusted to keep the caret visible.
-      # @param new_caret [Integer]
-      def caret=(new_caret)
-        new_caret = new_caret.clamp(0, @text.length)
-        return if @caret == new_caret
-
-        @caret = new_caret
-        adjust_top_display_row
-        invalidate
-      end
-
-      def focusable? = true
-
-      def tab_stop? = true
-
       # @return [Point, nil]
       def cursor_position
         return nil if rect.empty?
@@ -90,32 +49,6 @@ module Tuile
         Point.new(rect.left + col.clamp(0, rect.width - 1), rect.top + screen_row)
       end
 
-      # @param key [String]
-      # @return [Boolean]
-      def handle_key(key)
-        return false unless active?
-        return true if super
-
-        case key
-        when Keys::LEFT_ARROW then self.caret = @caret - 1
-        when Keys::RIGHT_ARROW then self.caret = @caret + 1
-        when Keys::CTRL_LEFT_ARROW then self.caret = word_left
-        when Keys::CTRL_RIGHT_ARROW then self.caret = word_right
-        when Keys::UP_ARROW then move_caret_vertical(-1)
-        when Keys::DOWN_ARROW then move_caret_vertical(1)
-        when *Keys::HOMES then move_caret_to_row_start
-        when *Keys::ENDS_ then move_caret_to_row_end
-        when *Keys::BACKSPACES then delete_before_caret
-        when Keys::DELETE then delete_at_caret
-        when Keys::ENTER then insert_char("\n")
-        else
-          return insert_char(key) if printable?(key)
-
-          return false
-        end
-        true
-      end
-
       # @param event [MouseEvent]
       # @return [void]
       def handle_mouse(event)
@@ -133,12 +66,6 @@ module Tuile
         end
       end
 
-      # Same SGR palette as {Component::TextField} for visual consistency.
-      # @return [String]
-      ACTIVE_BG_SGR = TextField::ACTIVE_BG_SGR
-      # @return [String]
-      INACTIVE_BG_SGR = TextField::INACTIVE_BG_SGR
-
       # @return [void]
       def repaint
         return if rect.empty?
@@ -160,6 +87,36 @@ module Tuile
 
       protected
 
+      # @return [void]
+      def on_text_mutated
+        @display_rows = nil
+        adjust_top_display_row
+      end
+
+      # @return [void]
+      def on_caret_mutated
+        adjust_top_display_row
+      end
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_text_input_key(key)
+        case key
+        when Keys::UP_ARROW then move_caret_vertical(-1)
+        when Keys::DOWN_ARROW then move_caret_vertical(1)
+        when *Keys::HOMES then move_caret_to_row_start
+        when *Keys::ENDS_ then move_caret_to_row_end
+        when *Keys::BACKSPACES then delete_before_caret
+        when Keys::DELETE then delete_at_caret
+        when Keys::ENTER then insert_char("\n")
+        else
+          return insert_char(key) if Keys.printable?(key)
+
+          return super
+        end
+        true
+      end
+
       # @return [void]
       def on_width_changed
         super
@@ -298,40 +255,12 @@ module Tuile
       # @param char [String]
       # @return [Boolean] always true.
       def insert_char(char)
-        @text = @text.dup.insert(@caret, char)
+        new_text = @text.dup.insert(@caret, char)
         @caret += char.length
-        @display_rows = nil
-        adjust_top_display_row
-        invalidate
-        @on_change&.call(@text)
+        self.text = new_text
         true
       end
 
-      # @return [void]
-      def delete_before_caret
-        return if @caret.zero?
-
-        @text = @text.dup
-        @text.slice!(@caret - 1)
-        @caret -= 1
-        @display_rows = nil
-        adjust_top_display_row
-        invalidate
-        @on_change&.call(@text)
-      end
-
-      # @return [void]
-      def delete_at_caret
-        return if @caret >= @text.length
-
-        @text = @text.dup
-        @text.slice!(@caret)
-        @display_rows = nil
-        adjust_top_display_row
-        invalidate
-        @on_change&.call(@text)
-      end
-
       # Keeps the caret visible by scrolling vertically.
       # @return [void]
       def adjust_top_display_row
@@ -347,30 +276,6 @@ module Tuile
         max_top = (rows.size - rect.height).clamp(0, nil)
         @top_display_row = @top_display_row.clamp(0, max_top)
       end
-
-      # @param key [String]
-      # @return [Boolean]
-      def printable?(key)
-        key.length == 1 && key.ord >= 0x20 && key.ord < 0x7f
-      end
-
-      # Same semantics as {TextField}'s ctrl+left.
-      # @return [Integer]
-      def word_left
-        c = @caret
-        c -= 1 while c.positive? && @text[c - 1].match?(/\s/)
-        c -= 1 while c.positive? && !@text[c - 1].match?(/\s/)
-        c
-      end
-
-      # Same semantics as {TextField}'s ctrl+right.
-      # @return [Integer]
-      def word_right
-        c = @caret
-        c += 1 while c < @text.length && !@text[c].match?(/\s/)
-        c += 1 while c < @text.length && @text[c].match?(/\s/)
-        c
-      end
     end
   end
 end