tuile 0.7.0 → 0.9.0

data/book/08-testing.md

@@ -0,0 +1,186 @@
+# 8. Testing a Tuile app
+
+Every chapter so far has, quietly, also been about this one. When chapter
+2 said components *invalidate* rather than paint, and write into a back
+*buffer* rather than to the terminal — that was a testing decision as much
+as a rendering one. When chapter 4 insisted everything runs on one thread
+through a queue you could swap out — same. A Tuile app is testable without
+a terminal not because someone bolted on a test mode, but because the
+framework never actually needed the terminal. It needed a `Screen`, a
+buffer, and an event queue, and each of those has an in-memory double that
+behaves like the real thing minus the I/O.
+
+So this chapter is the payoff. It shows how to exercise a UI in a plain
+unit test — instantiate a component, poke it, and read back exactly what
+it drew — and, when that isn't enough, how to drive the whole real script
+through a pseudo-terminal.
+
+## The fake screen, and why it resets
+
+The singleton `Screen` from chapter 4 is the thing tests replace. Two
+class methods bracket every example:
+
+```ruby
+before { Screen.fake }
+after  { Screen.close }
+```
+
+`Screen.fake` installs a {Tuile::FakeScreen} as the process singleton — a
+`Screen` subclass with the terminal amputated. It has a fixed 160×50
+viewport (so geometry is deterministic, independent of whoever's terminal
+runs the suite), it writes nothing to any TTY, its `check_locked` is a
+no-op so you can mutate the UI freely from the test thread without holding
+the UI lock, and its event queue is the synchronous {Tuile::FakeEventQueue}
+(more on that below). It also pins the color scheme to `:dark`, skipping
+the OSC 11 probe from chapter 6 — a probe would otherwise write an escape
+query to the test runner's terminal and swallow its input.
+
+`Screen.close` matters as much as `fake` does, and the reason is the
+singleton itself. Because there is exactly one `Screen` per process
+(chapter 4), a screen left standing after one example is the *same* screen
+the next example sees — its tree, its focus, its invalidation set, all
+leaked forward. `close` tears the singleton down so each example starts
+from nothing. Skip the `after` and you get the classic singleton test
+smell: passes in isolation, fails in suite, order-dependent. The pair is
+not boilerplate you can trim.
+
+## Asserting what got painted
+
+Here's where the back buffer earns its keep. Recall from chapter 2 that
+components don't emit escape sequences — they write styled cells into
+`Screen#buffer`, and only a flush turns that into wire bytes. In a test
+that means the buffer *is* the rendered screen, sitting in memory, fully
+inspectable, before any diffing or I/O. You assert against it directly.
+
+The rhythm is: build the component, give it a `rect`, repaint, read the
+buffer back over that rect.
+
+```ruby
+label = Component::Label.new
+label.rect = Rect.new(0, 0, 10, 1)
+label.text = "hi"
+label.repaint
+
+assert_equal ["hi        "], Screen.instance.buffer.region_text(label.rect)
+```
+
+{Tuile::Buffer#region_text} returns the plain text of each row in the
+rect, one string per row (trailing pad included — the label fills its
+width). Its sibling {Tuile::Buffer#region_ansi} returns the same rows *with
+their SGR styling* rendered back into ANSI, which is what you assert
+against when the test is about *color* — that a focused field painted its
+active-background, say, or that a theme flip changed a hint's hue. And
+{Tuile::Buffer#cell} gives you a single cell's grapheme and style for a
+pinpoint check. Everything is scoped to a `rect`, so you assert about a
+component's own region without caring what surrounds it.
+
+What you do *not* assert content against is `prints`. On a FakeScreen,
+`prints` captures only what actually went "to the wire" — cursor
+positioning, housekeeping escapes, and the assembled frame string. Content
+lives in the buffer; cursor behavior lives in `prints`. Keeping the two
+apart is deliberate, and mixing them up is the most common way a first
+Tuile test goes wrong.
+
+## Driving the system
+
+There are two altitudes at which you feed input, and picking the right one
+is most of writing a good Tuile test.
+
+**Low: call the component directly.** {Tuile::Component#handle_key} and
+`handle_mouse` are public, and calling them straight tests a component's
+own logic in isolation — no focus, no dispatch, just "given this key, does
+the list move its cursor?" `handle_key` returns whether it consumed the
+key, so you assert on that too:
+
+```ruby
+list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
+list.handle_mouse(MouseEvent.new(:left, 5, 2))
+```
+
+**High: go through the screen.** {Tuile::Screen#handle_key} runs the *full*
+dispatch pipeline from chapter 5 — Tab cycling, global shortcuts, the
+subtree `key_shortcut` search, then the focus chain. When your test is
+about routing — that a shortcut jumps focus, that a modal popup traps Tab,
+that a focused text field swallows a key its sibling would otherwise claim
+— you drive `Screen.instance.handle_key` and let the real machinery run.
+Set focus the way production does, with `screen.focused = component` or
+`component.focus`.
+
+Two more test-only hooks close the loop. After you mutate something, call
+`Screen.instance.repaint` to flush the pending invalidations into the
+buffer — the coalesced repaint that chapter 2 said happens once per tick,
+triggered by hand because there's no loop running to trigger it. (This is
+a *test* affordance; production code never calls `repaint`, it just
+invalidates and lets the loop coalesce.) And to check invalidation itself
+— that a setter did, or deliberately didn't, mark its component dirty —
+`Screen.instance.invalidated?(component)` and `invalidated_clear` let you
+assert on the set directly.
+
+## Why background code just works
+
+Chapter 4's rule was that background threads marshal UI work back with
+`screen.event_queue.submit { … }`. That rule has a happy consequence for
+tests: under the {Tuile::FakeEventQueue}, `submit` **runs its block
+synchronously, right now, on the calling thread.** There is no loop, no
+thread, no waiting. So code that in production hands work across the
+thread boundary — a `LogWindow#log`, a worker posting a result — executes
+inline the moment the test calls it, and the effect is visible on the very
+next line. Posted *events* are simply discarded (a test isn't running the
+loop that would consume them), and `check_locked` passing for free means
+none of this trips the lock guard.
+
+The one thing with no clock is animation. `tick` on the fake returns a
+timeless ticker that fires only when the test tells it to: call
+`event_queue.tick_once` to pump every registered ticker one frame. A test
+that wants to advance an animation five frames calls `tick_once` five
+times — frame cadence is the test's to decide, since there's no real time
+passing.
+
+## End to end, through a real terminal
+
+Unit tests with the fake cover component logic and rendering, which is
+most of what you write. But some things only exist when the *real* app
+runs: the event loop actually looping, raw-mode key decoding, the WINCH
+trap, a live color-scheme flip. For those, Tuile's own suite spawns the
+real example script in a pseudo-terminal and talks to it like a user
+would. The `spec/examples/` tests are the template.
+
+The shape is always the same. Spawn the script under `PTY.spawn`; read its
+output until a glyph you know it paints appears — that single wait proves a
+lot at once (the tree built, a repaint ran, and the loop is now parked in
+the key wait); write a keystroke; assert the process exits cleanly.
+
+```ruby
+PTY.spawn("bundle", "exec", "ruby", "-Ilib", "examples/hello_world.rb") do |reader, writer, pid|
+  buffer = String.new
+  Timeout.timeout(10) do
+    buffer << reader.readpartial(4096) until buffer.include?("Hello, world!")
+  end
+  writer.write("q")
+  Timeout.timeout(5) { Process.wait(pid) }
+  assert_equal 0, $CHILD_STATUS.exitstatus
+end
+```
+
+This is the only place the whole stack is exercised together, and it's
+where you'd test something like the mode-2031 flip from chapter 6:
+wait for the dark-theme hint to paint, write the terminal's
+`\e[?997;2n` light report into the PTY, then wait for the *light* hint —
+which passes only if the entire chain (key-thread drain, event parse,
+theme reassignment, full repaint) actually ran end to end. The cost is
+that PTY tests are slower, terminal-dependent, and Linux/macOS only
+(Ruby's stdlib `PTY` isn't on Windows), so they stay a thin top layer over
+a broad base of fake-screen unit tests — the classic pyramid.
+
+---
+
+That closes the book. You've followed Tuile from the outside in and back
+out: a tree of components (chapter 1) that repaint through a back buffer
+without flicker (chapter 2), sized top-down by their parents (chapter 3),
+driven by a single-threaded event loop (chapter 4), with keys routed by
+focus (chapter 5) and accents drawn from a terminal-following theme
+(chapter 6); then the library you assemble from (chapter 7), and finally
+the fakes that let you test all of it with no terminal in sight (this
+one). The recurring lesson is the one the name promises: small pieces, each
+doing an obvious thing, composed. The framework is small because the ideas
+are few — and now they're all yours to build on.

data/book/README.md

@@ -0,0 +1,79 @@
+# The Tuile guide
+
+A short, sequential guide to building terminal UIs with Tuile. Each
+chapter builds on the vocabulary the previous one established, so
+reading order matters — the layout chapter assumes the component tree
+from chapter 1, focus assumes the event loop, and so on. Don't jump
+into chapter 5 without chapters 1 and 2 first.
+
+If you want the reference instead of the narrative, every public class
+and module is documented with YARD headers in the sources. Run
+`bundle exec rake yard` for a browsable local site, or — once the gem
+is published — see <https://rubydoc.info/gems/tuile>. The division of
+labour: this guide teaches concepts and the *why*; the rdoc carries the
+precise per-method technical truth. When the guide needs a signature it
+links to the rdoc rather than restating it.
+
+## How the guide is shaped
+
+Chapters 1–2 are the **base vocabulary** — the component tree and the
+repaint model that every later chapter leans on. Chapter 3 is the heart
+of Tuile's design: layout is top-down and absolute, and the chapter
+argues *why that is enough* — the "C64" case for hand-placed
+coordinates on a character grid — rather than reaching for the
+negotiated min/pref/max machinery of desktop and web toolkits.
+
+Chapters 4–6 are the **runtime**: the single-threaded event loop and
+how to do background work safely, focus and keyboard dispatch, and
+theming (including live OS light/dark flips). Chapters 7–8 close out
+**narratively** — a tour of the shipped component toolbox framed around
+when and why to reach for each, and how to test a Tuile app end to end.
+Those two lean on the rdoc for the exact APIs; the guide keeps to the
+walkthroughs and use-cases.
+
+The book grows organically — a chapter exists when a concept has earned
+one, not to fill an outline.
+
+## Chapters
+
+1. **[Your first Tuile app](01-first-app.md).** Install, then a
+   hello-world walkthrough. Establishes the base vocabulary the rest of
+   the guide leans on: the singleton `Tuile::Screen`, the tree of
+   `Tuile::Component`s under `ScreenPane`, and the "build a tree, run
+   the loop" shape of every Tuile program.
+2. **[How the screen repaints](02-repaint.md).** Why components never
+   write to the terminal directly. `invalidate` → the back buffer →
+   a minimal diff → one synchronized flush per tick. The "cover your
+   own `rect`" contract, and why the whole model is flicker-free
+   without damage tracking or clipping.
+3. **[Layout: the parent sets the size](03-layout.md).** The heart of
+   the design. Top-down, absolute, integer coordinates; a parent
+   assigns its children's `rect` and components never negotiate a size.
+   The C64 argument for *why simple layouting is enough* on a character
+   grid, `Layout::Absolute` and the `rect=` override, `Fraction` for
+   sizing a popup against the screen, and resize as a discrete
+   recompute. Geometry primitives (`Point` / `Size` / `Rect`) live here.
+4. **[The event loop and background work](04-event-loop.md).** The
+   single-threaded rule: all UI mutation happens on the loop thread.
+   The event queue, marshalling work back from a background thread with
+   `submit`, and how terminal resize (`SIGWINCH`) is plumbed through the
+   same queue rather than handled off the signal.
+5. **[Focus and the keyboard](05-focus.md).** The focus chain and
+   `focusable?`, and the order in which a keystroke is offered to the
+   tree — Tab, global shortcuts, a component's `key_shortcut`, then
+   `handle_key`. How a focused text field swallows printable keys, and
+   how `keyboard_hint` drives the status bar.
+6. **[Theming](06-theming.md).** Semantic color tokens read at paint
+   time, light/dark auto-detection at startup and live OS appearance
+   flips, pairing variants in a `ThemeDef`, app-specific custom tokens,
+   and rebuilding theme-derived content in `on_theme_changed`.
+7. **[The component library](07-components.md).** A narrative tour of
+   the shipped toolbox — Window, List, the text inputs and views,
+   Popup, and the window conveniences — framed around *when and why*
+   you reach for each. Signatures stay in the rdoc.
+8. **[Testing a Tuile app](08-testing.md).** The testing approach:
+   `FakeScreen`, asserting against the painted buffer, driving
+   invalidation, and PTY-based end-to-end tests of runnable scripts.
+
+All eight chapters are currently **stubs** — the skeleton is in place so
+the numbering is stable; prose lands chapter by chapter.

data/examples/hello_world.rb

@@ -14,8 +14,7 @@ require "tuile"
 # Tuile::Screen.instance during invalidate/repaint hooks.
 screen = Tuile::Screen.new
 
-label = Tuile::Component::Label.new
-label.text = "Hello, world!"
+label = Tuile::Component::Label.new("Hello, world!")
 
 window = Tuile::Component::Window.new("Tuile")
 window.content = label

data/examples/sampler.rb

@@ -67,6 +67,7 @@ module SamplerExample
       ["Label",        :build_label],
       ["TextField",    :build_text_field],
       ["TextArea",     :build_text_area],
+      ["Slash menu",   :build_slash_demo],
       ["TextView",     :build_text_view],
       ["Button",       :build_buttons],
       ["List",         :build_list],
@@ -87,6 +88,11 @@ module SamplerExample
     end
 
     def load_entry(idx)
+      # The slash-menu demo parks a non-modal overlay on the pane (it lives
+      # outside the right pane's content tree), so close it before swapping
+      # demos or it would linger over the next one.
+      @slash_overlay.close if @slash_overlay&.open?
+      @slash_overlay = nil
       caption, builder = ENTRIES[idx]
       @right_window.caption = caption
       @right_window.content = send(builder)
@@ -135,6 +141,64 @@ module SamplerExample
       end
     end
 
+    # Slash commands the demo offers; the menu filters these by what's typed.
+    SLASH_COMMANDS = %w[/help /list /open /save /clear /quit].freeze
+
+    # A non-modal Popup used as an autocomplete menu. Focus (and the caret)
+    # stays in the TextArea the whole time: an `on_change` listener refills the
+    # menu, an `on_key` interceptor forwards Up/Down/Enter/ESC to it while it's
+    # open, and the menu floats above the field, anchored to the caret. None of
+    # this is baked into TextArea — it's all assembled here from stock hooks.
+    def build_slash_demo
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Non-modal Popup as an autocomplete menu. Type a slash command\n" \
+                    "(try \"/\" or \"/s\"). The menu floats above the field without taking\n" \
+                    "focus: Down/Up move the selection, Enter accepts, ESC dismisses, and\n" \
+                    "ordinary typing keeps editing the field and refilters the menu."
+      area = Tuile::Component::TextArea.new
+
+      list = Tuile::Component::List.new
+      list.cursor = Tuile::Component::List::Cursor.new
+      list.show_cursor_when_inactive = true # highlight the selection though focus stays in the field
+      window = Tuile::Component::Window.new("Commands").tap { _1.content = list }
+      overlay = Tuile::Component::Popup.new(content: window, modal: false)
+      @slash_overlay = overlay
+
+      refill = lambda do
+        matches = slash_matches(area)
+        if matches.empty?
+          overlay.close if overlay.open?
+        else
+          overlay.open unless overlay.open?
+          list.lines = matches
+          anchor_overlay(overlay, area)
+        end
+      end
+
+      area.on_change = ->(_text) { refill.call }
+      list.on_item_chosen = ->(_idx, line) { accept_slash_command(area, line.to_s) }
+      area.on_key = lambda do |key|
+        next false unless overlay.open?
+
+        case key
+        when Tuile::Keys::UP_ARROW, Tuile::Keys::DOWN_ARROW, Tuile::Keys::ENTER
+          list.handle_key(key) # works though the list is unfocused — dispatch gates on focus, not the list
+        when Tuile::Keys::ESC
+          overlay.close
+          true
+        else
+          false
+        end
+      end
+
+      panel(prompt, area) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 4)
+        area_height = [inner.height - 7, 4].max
+        area.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, area_height)
+      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" \
@@ -301,6 +365,51 @@ module SamplerExample
       end
     end
 
+    # The run of non-space characters ending at the caret, when it starts with
+    # "/" — i.e. the slash command being typed — or nil.
+    def slash_token(area)
+      text = area.text
+      caret = area.caret
+      start = caret
+      start -= 1 while start.positive? && !text[start - 1].match?(/\s/)
+      token = text[start...caret].to_s
+      token.start_with?("/") ? token : nil
+    end
+
+    # Commands matching the slash token at the caret (empty when not in one).
+    def slash_matches(area)
+      token = slash_token(area)
+      return [] if token.nil?
+
+      SLASH_COMMANDS.select { _1.start_with?(token) }
+    end
+
+    # Replaces the slash token at the caret with `command` plus a trailing
+    # space, then drops the caret after it (which re-fires on_change → refill,
+    # so the now-tokenless text closes the menu).
+    def accept_slash_command(area, command)
+      text = area.text
+      caret = area.caret
+      start = caret
+      start -= 1 while start.positive? && !text[start - 1].match?(/\s/)
+      area.text = "#{text[0...start]}#{command} #{text[caret..]}"
+      area.caret = start + command.length + 1
+    end
+
+    # Positions the overlay just below the caret, flipping above when there's
+    # no room beneath, and clamps it to the screen.
+    def anchor_overlay(overlay, area)
+      caret = area.cursor_position
+      return if caret.nil?
+
+      screen_size = Tuile::Screen.instance.size
+      size = overlay.rect
+      top = caret.y + 1
+      top = [caret.y - size.height, 0].max if top + size.height > screen_size.height - 1
+      left = caret.x.clamp(0, [screen_size.width - size.width, 0].max)
+      overlay.rect = Tuile::Rect.new(left, top, size.width, size.height)
+    end
+
     # Carves a 2-column padding out of the panel rect so the demo content
     # doesn't run flush to the window border.
     def inner_rect(rect)

data/lib/tuile/ansi.rb

@@ -11,5 +11,21 @@ module Tuile
     # background, and text attributes.
     # @return [String]
     RESET = "\e[0m"
+
+    # Begin Synchronized Update (DEC private mode 2026, "Synchronized
+    # Output"). The terminal stops refreshing its display and buffers every
+    # subsequent write until {SYNC_END}, then composites the whole batch
+    # atomically — so a multi-cell repaint is never shown half-drawn. This is
+    # what stops flicker when a frame redraws a large region (e.g. the
+    # full-scene repaint a shrinking popup forces). Terminals without support
+    # ignore the private-mode set, so it's a safe no-op there. {Screen#repaint}
+    # wraps its single frame-buffer flush in this pair.
+    # @return [String]
+    SYNC_BEGIN = "\e[?2026h"
+
+    # End Synchronized Update — see {SYNC_BEGIN}. Releases the buffered frame
+    # and lets the terminal repaint.
+    # @return [String]
+    SYNC_END = "\e[?2026l"
   end
 end