tuile 0.8.0 → 0.10.0

data/book/08-testing.md

@@ -0,0 +1,199 @@
+# 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 pane.** {Tuile::ScreenPane#handle_key} runs the
+dispatch rung from chapter 5 that routing is actually about: delivery to
+{Tuile::Screen#focused}, then the bubble up its ancestor chain to the scope
+root. So when your test is about routing — that a layout's one-key pane jump
+fires, that a focused text field swallows a key its ancestor would otherwise
+claim, that an open modal keeps the content beneath it from seeing keys — you
+drive the pane and let the real machinery run:
+
+```ruby
+screen.focused = list                # focus as production does — or list.focus
+assert screen.pane.handle_key("1")   # the layout's ancestor binding fires
+```
+
+The two rungs *above* the pane have their own doors, because `Screen`'s own
+`handle_key` — the top of the ladder — is private: it belongs to the key
+thread, not to app code. Tab cycling is {Tuile::Screen#focus_next} /
+`focus_previous`, both already scoped to the topmost modal popup, which is
+what "a popup traps Tab" means. A global shortcut is a block you registered,
+so test the action it calls; the registry itself is a lookup table `Screen`
+consults before handing the key to the pane, and `register_global_shortcut`
+is worth a test only for what it *rejects* (printables, Tab, `EDITING_KEYS`).
+
+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/09-styled-text.md

@@ -0,0 +1,132 @@
+# 9. Styled text
+
+Everything Tuile draws is, eventually, text with colors on it — a
+highlighted list row, a red error label, a border in the active accent.
+The value type that carries "text plus styling" through the whole
+framework is {Tuile::StyledString}, and it's worth one chapter of *why*,
+because the obvious representation — a plain `String` with ANSI escape
+codes threaded through it — is the one Tuile deliberately does *not* use.
+
+## Why not just a String with escape codes in it
+
+A terminal styles text with SGR escape sequences: `"\e[31mred\e[0m"` is
+the word "red" in red. It's tempting to treat a styled string as exactly
+that — a normal `String` that happens to contain those bytes — and let
+the terminal sort it out.
+
+The trouble shows up the moment you do anything *structural* to the text.
+Slice out columns 5 through 10: which colors are active at column 5? To
+answer, you have to scan every escape sequence from the start of the
+string, tracking the running SGR state, because the color at column 5 was
+set by some `\e[...m` that might be twenty characters earlier. Word-wrap
+it across a narrow viewport: every break point needs that same running
+state re-established on the next line, or the color bleeds or resets
+wrong. Concatenate two of them: whose reset wins? Every operation becomes
+"parse the SGR state machine, figure out what's active here, splice
+carefully." The escape codes and the text are tangled together, and the
+tangle has to be re-untangled on every edit.
+
+{Tuile::StyledString} untangles it once, structurally. A styled string is
+a sequence of **spans**, each a maximal run of characters that share one
+complete {Tuile::StyledString::Style} — foreground, background, bold,
+italic, underline, strikethrough. The spans are non-overlapping and tile
+the whole string: every character belongs to exactly one span, and that
+span's `style` *is* the character's style. There are no overlay layers to
+merge, no running state to reconstruct. "What's the style at column 5?"
+is just "which span contains column 5?" — a lookup, not a replay.
+
+That's the trade. You pay one extra type — you construct or parse a
+{Tuile::StyledString} instead of building a raw `String` — and in return
+slicing, wrapping, and concatenation become ordinary operations on a list
+of spans, each of which already knows its own style. For a framework that
+slices and wraps text constantly, on every repaint, that's the right side
+of the trade.
+
+## The algebra
+
+Once text is spans, the operations you'd want on a string come back, but
+style-aware. You concatenate with `+` (a plain `String` operand is parsed
+first, so embedded escapes round-trip). You take substrings by *display
+column* with `slice` — display column, not byte offset, because a
+fullwidth CJK character is two columns wide and a combining mark is zero,
+and the terminal cares about columns. You split on newlines with `lines`,
+word-wrap to a width with `wrap`, and truncate-with-ellipsis with
+`ellipsize`. Every one of them returns a fresh {Tuile::StyledString} with
+the spans carried across the cut intact — the value is immutable and its
+spans are frozen and shared, so these are cheap.
+
+Two details are worth knowing because they're choices, not accidents.
+Slicing **never splits a glyph**: if a two-column character straddles the
+boundary of your slice, it's dropped rather than rendered as half a
+character, which the terminal couldn't do anyway. "Glyph" there means a
+*grapheme cluster*, not a character, and the distinction is not pedantic —
+a letter plus its combining accent is two characters and one glyph, and a
+slice that kept the letter but dropped the mark would hand you back a
+visibly different word. Emoji make the same point louder: a thumbs-up plus
+a skin-tone modifier is two characters, one glyph, and two columns. Tuile
+measures clusters throughout and credits a combined emoji its real width
+rather than adding up its pieces, so text with emoji in it lays out and
+paints at the same size. And wrapping guarantees
+no output line exceeds the target width *whenever every character fits in
+that width* — a single glyph wider than the whole viewport still lands on
+its own line at its natural width, because there's nowhere narrower to put
+it. The exact signatures live in the rdoc; this is the shape of the
+toolbox.
+
+## Rendering and the minimal diff
+
+Two spans, both red, sitting next to each other, should not each re-emit
+`\e[31m` — the terminal is already red. {Tuile::StyledString#to_ansi}
+renders the spans to escape codes by **diffing** each span's style against
+the one before it, emitting only the codes that actually changed. A
+transition back to the plain default style emits a single `\e[0m` rather
+than laboriously turning each attribute off. The rendered run always
+closes with `\e[0m` if it ended non-default, so styling never bleeds into
+whatever the terminal prints next.
+
+This isn't just tidiness. The same style-diffing logic
+({Tuile::StyledString::Style#sgr_to}) is what the back buffer uses when it
+flushes changed cells to the terminal (chapter 2) — cell-to-cell there,
+span-to-span here, identical minimal sequences. Styled text and the
+flicker-free repaint model are the same idea at two scales: never rewrite
+what's already correct.
+
+## The parser: strict by default, lenient on request
+
+You can go the other way too — parse an ANSI-coded `String` *into* spans
+with {Tuile::StyledString.parse}. Here Tuile makes a sharp choice that's
+easy to get wrong, so it's worth stating plainly: **the parser is strict
+by default.**
+
+Strict means it recognizes exactly the SGR codes that map to a
+{Tuile::StyledString::Style}'s attributes — the foreground and background
+colors, bold, italic, underline, strikethrough — and *raises* on anything
+else. An unmodeled attribute like blink or reverse video, an unknown SGR
+code, a non-SGR escape like a cursor move or an OSC sequence: all of them
+are a {Tuile::StyledString::ParseError}, not a shrug. The reason is a
+contract worth protecting: `parse(to_ansi(x)) == x`. If parsing silently
+dropped what it didn't understand, that round-trip would quietly lie, and
+a styled string that survived a save/load cycle might come back subtly
+different. Strict parsing keeps the round-trip honest — anything the model
+can't represent is refused at the door, not swallowed.
+
+But strictness is wrong for one common job: piping in colored output you
+didn't produce and don't control — `git --color` through a pager, a build
+tool's output, anything that sprinkles cursor moves and exotic attributes
+you have no intention of modeling. For that, pass `lenient: true`. Now the
+parser keeps the colors and attributes it understands and **discards
+everything else** — unmodeled codes, malformed extended colors, cursor
+moves, OSC and other string sequences, stray escapes — instead of
+raising. It's lossy by definition (`parse(x, lenient: true)` does not
+round-trip back to `x`), and that's the point: "give me the colors, throw
+the rest away." Strict for text you own and must preserve exactly; lenient
+for text you're borrowing and only want the colors from.
+
+---
+
+{Tuile::StyledString} is the quiet primitive under everything visible.
+You rarely construct one by hand for simple cases — a {Tuile::Component::Label}
+takes a plain `String` and wraps it for you — but the moment you render
+your own content with per-span colors (a log line, a syntax-highlighted
+snippet, a diff), this is the type you're building, and the theming hook
+from chapter 6 is where you rebuild it when the palette changes.

data/book/README.md

@@ -0,0 +1,85 @@
+# 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. Chapter 9 is a **deep dive** on
+`Tuile::StyledString`, the text primitive under everything the framework
+draws — read it when you start rendering your own styled content.
+
+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 three-rung order in which a keystroke is offered
+   to the tree — Tab, global shortcuts, then `handle_key` delivered to
+   focus and bubbling up its ancestors. Why scope-wide keys (pane jumps, a
+   form's default button) belong on an ancestor, and how `keyboard_hint`
+   drives the status bar.
+6. **[Theming](06-theming.md).** Semantic color tokens read at paint
+   time, opt-in component backgrounds that inherit down the tree
+   (`bg_color`), 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,
+   ProgressBar, 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.
+9. **[Styled text](09-styled-text.md).** A deep dive on
+   `Tuile::StyledString`, the span-based "text plus styling" value type
+   under everything Tuile draws: why spans instead of a `String` full of
+   escape codes, the style-aware algebra (slice/wrap/concat by display
+   column), minimal-diff rendering, and the strict-vs-lenient parser.

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