tuile 0.12.0 → 0.14.0

data/book/08-testing.md

@@ -28,10 +28,13 @@ 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
+runs the suite), it writes nothing to any TTY, and its event queue is the
+synchronous {Tuile::FakeEventQueue} (more on that below). You can mutate the
+UI directly from your example — and note there is no lock *bypass* doing
+that for you: the fake runs no loop, so `running?` is false and chapter 4's
+rule falls back to "the thread that created the screen," which is yours. A
+spec that mutates the UI from a **spawned** thread therefore raises, exactly
+as an app would. 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.
 
@@ -44,6 +47,17 @@ 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.
 
+One more line of setup earns its place if your app has a theme of its own. A
+fresh `Screen.fake` starts from the built-in {Tuile::ThemeDef}, so a
+component reading `theme[:my_token]` would `KeyError` in every example.
+Rather than assigning `Screen.instance.theme_def` in every `before` block,
+point the construction-time default at your definition once, in
+`spec_helper`:
+
+```ruby
+Tuile::ThemeDef.default = APP_THEME   # every Screen.fake now carries it
+```
+
 ## Asserting what got painted
 
 Here's where the back buffer earns its keep. Recall from chapter 2 that
@@ -94,9 +108,25 @@ key, so you assert on that too:
 
 ```ruby
 list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
+```
+
+**A mouse test needs the component mounted, where a key test doesn't.** A
+click doesn't only *do* something, it also *focuses* — and
+{Tuile::Screen#focused=} refuses a component that isn't on the pane, so
+`handle_mouse` on a component you never attached raises "is not attached to
+this screen". Give it a tree first:
+
+```ruby
+screen.content = list                      # a click focuses; focus needs a tree
+list.rect = Rect.new(0, 0, 10, 5)
 list.handle_mouse(MouseEvent.new(:left, 5, 2))
 ```
 
+That applies to containers too, and to more of them than you might expect:
+a click descends to every child whose rect contains the point, so testing a
+window's footer by clicking it exercises the window, the footer's slot and
+the footer, all of which want to be attached.
+
 **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

data/book/09-styled-text.md

@@ -29,7 +29,7 @@ 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
+italic, underline, strikethrough, inverse. 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?"
@@ -100,8 +100,8 @@ 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
+colors, bold, italic, underline, strikethrough, inverse — and *raises* on
+anything else. An unmodeled attribute like blink or conceal, 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

data/book/README.md

@@ -66,17 +66,19 @@ one, not to fill an outline.
    `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.
+   form's default button) belong on an ancestor, why a paste rides its own
+   path rather than the ladder, and how to write a status line over
+   `on_focus_changed` — Tuile draws none for you.
 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.
+   the shipped toolbox — the text inputs and views, the value fields, the
+   selectors, Button, ProgressBar, Window, TabSheet, MenuBar, 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.

data/examples/file_commander.rb

@@ -4,7 +4,9 @@
 # Tuile two-pane file commander. Two windows side by side, each showing a
 # directory listing. Tab switches active pane; arrows / jk move the cursor;
 # Enter descends into a directory (no-op on a regular file); Backspace
-# ascends to the parent. The header label shows the active pane's cwd.
+# ascends to the parent. The header label shows the active pane's cwd, and a
+# static status line spells out the keys — Tuile draws no status bar and
+# reserves no row, so both are ordinary children of the layout.
 # Unreadable directories surface an InfoWindow. Layout follows the
 # terminal on resize (WINCH) — the framework dispatches a TTYSizeEvent and
 # the layout's `rect=` rebuilds the geometry.
@@ -80,7 +82,7 @@ module FileCommanderExample
       @on_cwd_changed&.call
     rescue SystemCallError => e
       @cwd = previous
-      Tuile::Component::InfoWindow.open("Cannot open", [path, e.message])
+      Tuile::Component::InfoWindow.open("Cannot open", "#{path}\n#{e.message}")
     end
 
     def load_entries
@@ -107,18 +109,6 @@ module FileCommanderExample
     end
   end
 
-  # A pane window that advertises navigation shortcuts in the status bar.
-  # The active window's `keyboard_hint` is rendered by {Tuile::Screen}
-  # alongside the global `q` quit hint, so all the user-facing controls
-  # land in one place.
-  class PaneWindow < Tuile::Component::Window
-    def keyboard_hint
-      "Tab #{screen.theme.hint("Switch")}  " \
-        "Enter #{screen.theme.hint("Open")}  " \
-        "Bksp #{screen.theme.hint("Up")}"
-    end
-  end
-
   # Top-level layout. Header label on the first row, two side-by-side
   # windows below. `rect=` re-runs on the initial mount and on every WINCH,
   # so the split tracks the terminal size automatically.
@@ -128,19 +118,34 @@ module FileCommanderExample
       @header = Tuile::Component::Label.new
       add(@header)
 
-      @left_window = PaneWindow.new
+      @left_window = Tuile::Component::Window.new
       @left_list = DirList.new(left_dir)
       @left_list.on_cwd_changed = method(:refresh_header)
       @left_window.content = @left_list
       @left_window.scrollbar = true
       add(@left_window)
 
-      @right_window = PaneWindow.new
+      @right_window = Tuile::Component::Window.new
       @right_list = DirList.new(right_dir)
       @right_list.on_cwd_changed = method(:refresh_header)
       @right_window.content = @right_list
       @right_window.scrollbar = true
       add(@right_window)
+
+      # The status line. Every key here works in both panes, so the row never
+      # changes and nothing needs to watch focus — a status line is only worth
+      # wiring to Tuile::Screen#on_focus_changed= when its text actually varies
+      # with the focused component. `theme.hint` bakes its colors in, so the
+      # one thing this label does watch is a light/dark flip.
+      @status = Tuile::Component::Label.new
+      render_status = lambda do
+        t = screen.theme
+        @status.text = "q #{t.hint("quit")}  Tab #{t.hint("Switch")}  " \
+                       "Enter #{t.hint("Open")}  Bksp #{t.hint("Up")}"
+      end
+      render_status.call
+      @status.on_theme_changed = render_status
+      add(@status)
     end
 
     attr_reader :left_window
@@ -150,8 +155,9 @@ module FileCommanderExample
       return if rect.empty?
 
       @header.rect = Tuile::Rect.new(rect.left, rect.top, rect.width, 1)
+      @status.rect = Tuile::Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
       body_top = rect.top + 1
-      body_height = [rect.height - 1, 0].max
+      body_height = [rect.height - 2, 0].max
       half = rect.width / 2
       @left_window.rect = Tuile::Rect.new(rect.left, body_top, half, body_height)
       @right_window.rect = Tuile::Rect.new(rect.left + half, body_top,

data/examples/hello_world.rb

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Tuile hello-world. A Window wrapping a Label.
+# Tuile hello-world. A Window wrapping a Label, over a status line the app
+# owns — Tuile draws no chrome of its own and reserves no row.
 #
 # Run from the gem root:
 #   bundle exec ruby -Ilib examples/hello_world.rb
@@ -14,12 +15,23 @@ require "tuile"
 # Tuile::Screen.instance during invalidate/repaint hooks.
 screen = Tuile::Screen.new
 
-label = Tuile::Component::Label.new("Hello, world!")
-
 window = Tuile::Component::Window.new("Tuile")
-window.content = label
+window.content = Tuile::Component::Label.new("Hello, world!")
+
+# The status line. `theme.hint` styles the *description* half of a "key what"
+# pair, and bakes the color in — so the label rebuilds itself from
+# `on_theme_changed` to follow a light/dark flip.
+status = Tuile::Component::Label.new
+render_status = -> { status.text = "q #{screen.theme.hint("quit")}" }
+render_status.call
+status.on_theme_changed = render_status
+
+# One row for the status line, everything else to the window.
+root = Tuile::Component::Layout::Vertical.new
+root.add(window, Tuile::Component::Layout::Expand[1])
+root.add(status, Tuile::Component::Layout::Fixed[1])
 
-screen.content = window
+screen.content = root
 window.focus
 begin
   screen.run_event_loop