tuile 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e96464e067ccbb78bd11cf6639b53dc4f53de48519f7e47143a594b520bb99c
-  data.tar.gz: 668bd3ac1b4130919949dce95867cccfa89dac387b6f164a2c7ea027cf04c1da
+  metadata.gz: 23a6288632a551240d224975faee1f71d477bb1465126d70915950f67c187650
+  data.tar.gz: 33e26892d2a625e85d5d2f2fd058a04080ef12ea38825cb2f9727a346f36c6a2
 SHA512:
-  metadata.gz: 6e9e20049c86bab8649b3d53604a61438f27608ae62d009c6a556fe76b146e186072c46a4c5036173c3b40197d8648dee855dce401d4536060f269e159a40c98
-  data.tar.gz: 2ddccc6f2d1664935ba7c64b523f09b3a1ba9a57c7c356620beef39fd623b4a76a60d7fd1fda109aa11e9a5693a911cc1736d0f07dc99aad507008726d3fd301
+  metadata.gz: 233960b007d8c81281e6726e605ab48e9bdc389399b796a4d9a19314e1be2bfab019a787ddc6ab8b421221010cb9402fdc102737fef085aaa326641b76275eed
+  data.tar.gz: 68b2425566e2a2586d686699df135a4a7fce835b0f2ca5f090204b3b82f6d3b6d7813375f9129e5256eea627be8df72e667694869d4ba475de55221c0db5ae8e

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 ## [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.
+- Add `Tuile::StyledString` for span-modeled ANSI styling, with `#wrap` (span-preserving word wrap), `#ellipsize` (width-bounded truncation), `#with_bg`, and an `EMPTY` shared instance.
+- Model `Label`, `List`, and `TextView` text as `StyledString`; pre-pad clipped/physical lines.
+- Extract `Tuile::Ansi` for shared ANSI helpers.
+- `Window#scrollbar=` accepts any content that exposes `scrollbar_visibility=`.
+- Document `TextView` in the README and `examples/sampler.rb`.
+- Remove `Tuile::Wrap` (superseded by `StyledString#wrap`).
+- Remove `Tuile::Truncate` (superseded by `StyledString#ellipsize`).
+
 ## [0.2.0] - 2026-05-15
 
 - Add `Component::TextArea` with multi-line editing, word navigation, and VT220-style Home/End handling.

data/README.md

@@ -79,7 +79,10 @@ Save it as `hello.rb` and run `ruby hello.rb`. Press `q` or `ESC` to exit.
 
 A larger demo lives in [`examples/file_commander.rb`](examples/file_commander.rb):
 a two-pane file browser with cursor navigation, header label, and a layout
-that follows terminal resize.
+that follows terminal resize. For a tour of every shipped component, run
+[`examples/sampler.rb`](examples/sampler.rb): a two-pane sampler where the
+left pane lists demos and the right pane loads the highlighted one. Tab /
+Shift+Tab move focus between the list and the demo's widgets.
 
 ## How it works
 
@@ -143,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
@@ -151,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
 
@@ -349,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/examples/sampler.rb

@@ -66,6 +66,7 @@ module SamplerExample
       ["Label",        :build_label],
       ["TextField",    :build_text_field],
       ["TextArea",     :build_text_area],
+      ["TextView",     :build_text_view],
       ["Button",       :build_buttons],
       ["List",         :build_list],
       ["Layout",       :build_layout],
@@ -133,6 +134,38 @@ module SamplerExample
       end
     end
 
+    def build_text_view
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Read-only viewer for prose. Word-wraps to width; ANSI formatting passes through.\n" \
+                    "Tab here, then: ↑↓ / jk scroll a line; PgUp/PgDn a page; Ctrl+U/D half a page; " \
+                    "Home/End / g/G jump to the edges."
+      window = Tuile::Component::Window.new("Excerpt")
+      view = Tuile::Component::TextView.new
+      view.text = "#{Rainbow("Tuile").green} is a small component-oriented terminal-UI framework built on top of " \
+                  "the TTY toolkit. Apps build a tree of Components under a singleton Screen; the screen runs " \
+                  "an event loop, dispatches keys and mouse events, and repaints invalidated components in " \
+                  "batch.\n\n" \
+                  "The name is #{Rainbow("French").cyan} for #{Rainbow("\"roof tile\"").yellow} — small pieces " \
+                  "that compose into a larger whole. This excerpt wraps to the viewer's current width; resize " \
+                  "the terminal to see the wrap recompute, and scroll to see the rest.\n\n" \
+                  "Components do not paint immediately. They call invalidate (which records them in the " \
+                  "Screen's pending-repaint set); after an event-loop tick drains the queue, Screen#repaint " \
+                  "walks the set, sorts by depth, and paints parents before children. Popups deliberately " \
+                  "overdraw the tiled tree on top.\n\n" \
+                  "All UI mutations must run on the thread that owns Screen#run_event_loop. Background work " \
+                  "marshals back via screen.event_queue.submit { … }. Most UI methods check the lock and " \
+                  "raise if you violate the contract; FakeScreen short-circuits the check so tests can mutate " \
+                  "freely."
+      window.content = view
+      window.scrollbar = true
+      panel(prompt, window) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
+        view_height = [inner.height - 5, 4].max
+        window.rect = Tuile::Rect.new(inner.left, inner.top + 4, inner.width, view_height)
+      end
+    end
+
     def build_buttons
       label = Tuile::Component::Label.new
       label.text = "Buttons fire on Enter, Space, or a left-click. Tab to focus, then activate."

data/lib/tuile/ansi.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tuile
+  # ANSI escape sequence constants. Tuile emits colors and text attributes
+  # via Rainbow, which produces **SGR** sequences ("Select Graphic
+  # Rendition", `ESC [ <params> m` — e.g. `\e[31m` red, `\e[1m` bold,
+  # `\e[0m` reset).
+  module Ansi
+    # SGR reset (`ESC [ 0 m`). Restores the terminal's default foreground,
+    # background, and text attributes.
+    # @return [String]
+    RESET = "\e[0m"
+  end
+end

data/lib/tuile/component/label.rb

@@ -2,38 +2,66 @@
 
 module Tuile
   class Component
-    # A label which shows static text. No word-wrapping; clips long lines.
+    # A label which shows static text. No word-wrapping; long lines are
+    # truncated with an ellipsis. Text is modeled as a {StyledString};
+    # {#text=} accepts a {String} (parsed via {StyledString.parse}, so
+    # embedded ANSI is honored) or a {StyledString} directly. {#text}
+    # always returns the {StyledString}.
     class Label < Component
       def initialize
         super
-        @lines = []
+        @text = StyledString::EMPTY
         @clipped_lines = []
+        @blank_line = ""
       end
 
-      # @param text [String, nil] draws this text. May contain ANSI formatting.
-      #   Clipped automatically.
+      # @return [StyledString] the current text. Defaults to an empty
+      #   {StyledString}.
+      attr_reader :text
+
+      # Replaces the text. A `String` is parsed via {StyledString.parse}
+      # (embedded ANSI is honored); a `StyledString` is used as-is; `nil` is
+      # coerced to an empty {StyledString}. Lines wider than {#rect} are
+      # truncated with an ellipsis at paint time.
+      # @param value [String, StyledString, nil]
       # @return [void]
-      def text=(text)
-        @lines = text.to_s.split("\n")
+      def text=(value)
+        new_text = StyledString.parse(value)
+        return if @text == new_text
+
+        @text = new_text
         @content_size = nil
-        update_clipped_text
+        update_clipped_lines
+        invalidate
       end
 
-      # @return [Size]
+      # @return [Size] longest hard-line's display width × number of hard
+      #   lines. Reported on the *unclipped* text — sizing is intrinsic to
+      #   the content, not the viewport. Empty text returns `Size.new(0, 0)`.
       def content_size
-        @content_size ||= begin
-          width = @lines.map { |line| Unicode::DisplayWidth.of(Rainbow.uncolor(line)) }.max || 0
-          Size.new(width, @lines.size)
-        end
+        @content_size ||=
+          if @text.empty?
+            Size::ZERO
+          else
+            hard_lines = @text.lines
+            width = hard_lines.map(&:display_width).max || 0
+            Size.new(width, hard_lines.size)
+          end
       end
 
+      # Paints the text into {#rect}.
+      #
+      # Skips the {Component#repaint} default's auto-clear: every row is
+      # painted explicitly (with pre-padded blanks past the last line), so
+      # the "fully draw over your rect" contract is met without an upfront
+      # wipe.
       # @return [void]
       def repaint
-        super
-        height = rect.height.clamp(0, nil)
-        lines_to_print = @clipped_lines.length.clamp(nil, height)
-        (0..lines_to_print - 1).each do |index|
-          screen.print TTY::Cursor.move_to(rect.left, rect.top + index), @clipped_lines[index]
+        return if rect.empty?
+
+        (0...rect.height).each do |row|
+          line = @clipped_lines[row] || @blank_line
+          screen.print TTY::Cursor.move_to(rect.left, rect.top + row), line
         end
       end
 
@@ -42,21 +70,31 @@ module Tuile
       # @return [void]
       def on_width_changed
         super
-        update_clipped_text
+        update_clipped_lines
       end
 
       private
 
+      # Recomputes {@clipped_lines} for the current text and rect width.
+      # Each line is ellipsized to fit, padded with trailing spaces out to
+      # the full width, and pre-rendered to ANSI so {#repaint} is just a
+      # lookup + screen.print per row. {@blank_line} covers rows past the
+      # last text line.
       # @return [void]
-      def update_clipped_text
-        len = rect.width.clamp(0, nil)
-        clipped = @lines.map do |line|
-          Truncate.truncate(line, length: len)
-        end
-        return if @clipped_lines == clipped
+      def update_clipped_lines
+        width = rect.width.clamp(0, nil)
+        @blank_line = " " * width
+        @clipped_lines = @text.lines.map { |line| pad_to(line.ellipsize(width), width).to_ansi }
+      end
 
-        @clipped_lines = clipped
-        invalidate
+      # @param line [StyledString]
+      # @param width [Integer]
+      # @return [StyledString]
+      def pad_to(line, width)
+        diff = width - line.display_width
+        return line if diff <= 0
+
+        line + StyledString.plain(" " * diff)
       end
     end
   end