tuile 0.16.0 → 0.17.0

data/book/08-testing.md

@@ -66,16 +66,21 @@ components don't emit escape sequences — they write styled cells into
 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.
+The rhythm is: build the component, have a parent place it at a rect,
+repaint, read the buffer back over that rect. A component never takes a
+rect from anyone but its parent's `relayout` — `rect=` raises anywhere
+else — so a test holds it in a `Layout::Absolute`, which places each child
+exactly where it was added:
 
 ```ruby
 label = Component::Label.new
-label.rect = Rect.new(0, 0, 10, 1)
 label.text = "hi"
-label.repaint
+holder = Component::Layout::Absolute.new
+holder.add(label, Rect.new(0, 0, 10, 1))
+Screen.instance.content = holder
+Screen.instance.repaint
 
-assert_equal ["hi        "], Screen.instance.buffer.region_text(label.rect)
+assert_equal ["hi        "], Screen.instance.buffer.region_text(label.absolute_rect)
 ```
 
 {Tuile::Buffer#region_text} returns the plain text of each row in the
@@ -88,6 +93,29 @@ active-background, say, or that a theme flip changed a hint's hue. And
 pinpoint check. Everything is scoped to a `rect`, so you assert about a
 component's own region without caring what surrounds it.
 
+That is what the *user* sees at those cells, a popup drawn over them
+included. Often a test wants something narrower — what this one component
+paints — and {Tuile::Testing.paint} answers that without a screen round
+trip. It paints the component and its whole subtree into a {Tuile::Buffer}
+of the component's own size, whose `(0, 0)` is the component's top-left:
+
+```ruby
+window = Component::Window.new("Settings")
+window.content = Component::Label.new("hi")
+Testing.place(window, Rect.new(0, 0, 12, 3))   # sized; nothing to attach
+
+assert_equal ["┌Settings──┐", "│hi        │", "└──────────┘"], Testing.paint(window).text
+```
+
+`Testing.place` puts a component at a rect through whatever places it —
+here a throwaway holder, since `window` has no parent — because `rect=`
+raises anywhere but a parent's `relayout`. It never attaches, and
+`Testing.paint` doesn't need it to. Because the buffer is the component's
+own, `cell(1, 0)` means column 1 *of the window*, and the classic mistake of
+reading the screen at `rect` instead of `absolute_rect` has nowhere to
+happen. Ancestors don't clip the paint, though their background shows
+through; popups aren't in the subtree, so they don't show at all.
+
 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
@@ -107,17 +135,33 @@ method* assembled, and the test never held a reference to it.
 one component matching a spec:
 
 ```ruby
-Testing.get(Component::Button, caption: "Save").handle_key?(Keys::ENTER)
+Testing.get(id: :save).handle_key?(Keys::ENTER)
 Testing.get(id: :amount).value = 42
 ```
 
-The spec is a class, an `id`, a caption, a block, or any combination of
-them — never a path through the hierarchy, which would break every time you
-nested one more layout. The class slot also takes a *mixin*, which is where
-the `Has*` family from chapter 7 pays off a second time:
+Those two lines drive the component directly, which is the right altitude for
+some tests and too low for others; the gestures later in this chapter are the
+same two lines with "could a user have done this?" asked first.
+
+The spec is a class, an `id`, a block, or any combination of them — never a
+path through the hierarchy, which would break every time you nested one more
+layout. The class slot also takes a *mixin*, which is where the `Has*` family
+from chapter 7 pays off a second time:
 `Testing.find(Component::HasBadInput)` finds every field in the tree whose
 parse can fail, whatever their classes.
 
+Notice what is *not* on that list: there is no way to look a component up by
+the text it shows. That is deliberate. Those handles are structural — they
+describe where a component sits and what kind of thing it is — while a caption
+is copy, and copy gets reworded by people who are not thinking about your
+specs. A test that breaks because "Save" became "Save changes" has told you
+nothing. When you really do want the text, the block says so and reads better
+for being explicit about the class:
+
+```ruby
+Testing.get(Component::Button) { _1.caption.to_s == "Save" }
+```
+
 The `id` in that second line is a plain `Symbol` tag you set on any
 component, purely so a test can ask for it back:
 
@@ -196,16 +240,19 @@ by hand tests a third of what a click is. Drive it through
 {Tuile::FakeScreen}, which posts the gesture the terminal would:
 
 ```ruby
-screen.content = list                      # a press focuses; focus needs a tree
-list.rect = Rect.new(0, 0, 10, 5)
+holder = Component::Layout::Absolute.new
+holder.add(list, Rect.new(0, 0, 10, 5))
+screen.content = holder                    # a press focuses; focus needs a tree
 screen.click(5, 2)                         # press then release, at that cell
 ```
 
 `click` is the whole gesture; `press` / `release` are its halves, for a test
 about what the grab does in between, and `scroll` / `move` post the other two
-events. They all take screen-absolute, 0-based coordinates, so a test asserts
-against the rect it assigned — and a press on a cell no component covers
-simply does nothing.
+events. They all take screen-absolute, 0-based coordinates, because that is what a
+terminal reports — so a test clicks at `button.absolute_rect.left`, not at
+`button.rect.left`, which is measured inside the button's parent. The component
+receives the press back in its own coordinates. A press on a cell no component
+covers simply does nothing.
 
 **High: go through the pane.** {Tuile::ScreenPane#handle_key?} runs the
 dispatch rung from chapter 5 that routing is actually about: delivery to
@@ -239,6 +286,59 @@ invalidates and lets the loop coalesce.) And to check invalidation itself
 `Screen.instance.invalidated?(component)` and `invalidated_clear` let you
 assert on the set directly.
 
+## Gestures: locating and driving in one line
+
+Put the two halves together and a gap appears between them. `Testing.get`
+refuses to hand you a hidden component, because it simulates a user — but the
+moment you have a handle, `handle_key?` and `value=` will do as they are told
+no matter what. A button under an open modal popup, a field in a collapsed
+panel: both drive perfectly from a test, and both are unreachable in the app
+you are shipping. The test passes; the feature is broken.
+
+The gestures close it. Each one asks whether a user could have done this, and
+raises with a dump of the tree when the answer is no:
+
+```ruby
+Testing.click(Testing.get(Component::Button, id: :save))
+Testing.set_value(Testing.get(Component::TextField, id: :name), "Zaphod")
+```
+
+`Testing.click` is `screen.click` aimed by component rather than by cell: it
+finds the top-left cell the component actually paints, checks a press there
+*reaches* it, and posts the real press and release. What it refuses is
+everything that would have clicked nothing — hidden, collapsed, or covered:
+
+```
+#<Button id=:save rect=(1,1 8x1) caption="Save"> is not clickable at 1,1:
+a press there reaches nothing — a modal popup is open
+```
+
+It does *not* raise when the press lands and nobody claims it. Clicking a
+`Label` is a thing a user can really do, and nothing happens; the gesture
+asserts the click was possible, not that it achieved something.
+
+`Testing.set_value` asks the keyboard's version of the same question: a field
+outside the current key scope — behind an open modal — refuses. It moves no
+focus, since no keystroke is involved, and assigns through `value=`, so it is
+the value-level shortcut rather than a simulation of typing: the editor's input
+filters never run.
+
+Written out, those calls nest inside-out. Activate the refinement and they read
+in the order they happen:
+
+```ruby
+using Tuile::Testing::Gestures        # top of the file, or inside one describe
+
+Testing.get(Component::TextField, id: :name)._value = "Zaphod"
+Testing.get(Component::Button, id: :save)._click
+```
+
+The leading underscore is a borrowing from Karibu-Testing, and it earns its keep
+on the first line: `_value =` sits one character from a real `value=`, and the
+mark is what tells a reader which is running. Being a refinement, it exists only
+where you `using` it — per file or per `describe`, never leaking to the next —
+and nothing is added to `Component`, so an app never sees it.
+
 ## Why background code just works
 
 Chapter 4's rule was that background threads marshal UI work back with

data/book/10-locale.md

@@ -201,7 +201,7 @@ Your own code does the same for a date you rendered into a
 the listener:
 
 ```ruby
-label.on_locale_changed = -> { label.text = due.strftime(screen.locale.date_formats.first) }
+label.on_locale_changed { label.text = due.strftime(screen.locale.date_formats.first) }
 ```
 
 One consequence to accept rather than defend against: a field holding a

data/book/README.md

@@ -18,7 +18,7 @@ links to the rdoc rather than restating it.
 
 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
+of Tuile's design: layout is top-down and parent-relative, 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.
@@ -47,13 +47,13 @@ one, not to fill an outline.
 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.
+   own `rect`" contract, the bound that enforces it, and why the whole
+   model is flicker-free without damage tracking.
 3. **[Layout: the parent sets the size](03-layout.md).** The heart of
-   the design. Top-down, absolute, integer coordinates; a parent
+   the design. Top-down, parent-relative, 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, the `Vertical` /
+   grid, the `relayout` override, `Layout::Absolute`, the `Vertical` /
    `Horizontal` box layouts and their three constraints (`Fixed` /
    `Percent` / `Expand`) as sugar over that same rule, `Fraction` for
    sizing a popup against the screen, and resize as a discrete

data/examples/file_commander.rb

@@ -40,18 +40,26 @@ module FileCommanderExample
   # navigation, and notifies a callback so the shared header label can be
   # rebuilt without the panes knowing about each other.
   class DirList < Tuile::Component::List
+    # What `on_cwd_changed` fires. An app's own event is a `Data.define`
+    # including the marker, exactly as the gem's are.
+    CwdChangedEvent = Data.define(:source, :cwd) { include Tuile::Event }
+
+    # @!method on_cwd_changed
+    #   Fired whenever this pane's `cwd` changes, or it takes focus — the shared
+    #   header rebuilds from it, so the two panes need not know about each other.
+    #   @return [Tuile::Listeners]
+    listener :on_cwd_changed
+
     def initialize(start_dir)
       super()
       self.cursor = Tuile::Component::List::Cursor.new
-      self.renderer = ->(entry) { Rainbow(entry[:display]).color(TYPE_COLORS[entry[:type]]) }
+      self.renderer = ->(entry, _w) { Rainbow(entry[:display]).color(TYPE_COLORS[entry[:type]]) }
       @cwd = File.expand_path(start_dir)
-      @on_cwd_changed = nil
       load_entries
-      self.on_item_chosen = method(:descend)
+      on_item_chosen << method(:descend)
     end
 
     attr_reader :cwd
-    attr_accessor :on_cwd_changed
 
     def handle_key?(key)
       return false unless active?
@@ -66,13 +74,13 @@ module FileCommanderExample
 
     def handle_focus
       super
-      @on_cwd_changed&.call
+      fire_cwd_changed
     end
 
     private
 
-    def descend(_index, entry)
-      target = File.expand_path(File.join(@cwd, entry[:name]))
+    def descend(event)
+      target = File.expand_path(File.join(@cwd, event.item[:name]))
       change_to(target) if File.directory?(target)
     end
 
@@ -81,13 +89,15 @@ module FileCommanderExample
       change_to(parent) if parent != @cwd
     end
 
+    def fire_cwd_changed = on_cwd_changed.fire(CwdChangedEvent.new(source: self, cwd: @cwd))
+
     def change_to(path)
       previous = @cwd
       @cwd = path
       load_entries
       self.cursor = Tuile::Component::List::Cursor.new
       self.scroll_top_row = 0
-      @on_cwd_changed&.call
+      fire_cwd_changed
     rescue SystemCallError => e
       @cwd = previous
       Tuile::Component::InfoWindow.open("Cannot open", "#{path}\n#{e.message}")
@@ -118,9 +128,9 @@ module FileCommanderExample
   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.
-  class FileCommander < Tuile::Component::Layout::Absolute
+  # windows below. `relayout` re-runs on the initial mount and on every
+  # WINCH, so the split tracks the terminal size automatically.
+  class FileCommander < Tuile::Component::Layout
     def initialize(left_dir, right_dir)
       super()
       @header = Tuile::Component::Label.new
@@ -128,21 +138,21 @@ module FileCommanderExample
 
       @left_window = Tuile::Component::Window.new
       @left_list = DirList.new(left_dir)
-      @left_list.on_cwd_changed = method(:refresh_header)
+      @left_list.on_cwd_changed << method(:refresh_header)
       @left_window.content = @left_list
       @left_window.scrollbar = true
       add(@left_window)
 
       @right_window = Tuile::Component::Window.new
       @right_list = DirList.new(right_dir)
-      @right_list.on_cwd_changed = method(:refresh_header)
+      @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
+      # wiring to Tuile::Screen#on_focus_changed when its text actually varies
       # with the focused component. `theme.fg` bakes its colors in, so the
       # one thing this label does watch is a light/dark flip.
       @status = Tuile::Component::Label.new
@@ -152,24 +162,25 @@ module FileCommanderExample
                        "Enter #{t.fg(:hint, "Open")}  Bksp #{t.fg(:hint, "Up")}"
       end
       render_status.call
-      @status.on_theme_changed = render_status
+      @status.on_theme_changed << render_status
       add(@status)
     end
 
     attr_reader :left_window
 
-    def rect=(new_rect)
-      super
-      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 - 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,
-                                           rect.width - half, body_height)
+    protected
+
+    # No `return if rect.empty?` guard: an empty pane still assigns every
+    # child, or they strand at their old coordinates (`D_empty_ancestor`).
+    def relayout
+      # A child's rect is relative to this layout, so nothing here names where
+      # the layout itself sits — moving it moves the whole pane for free.
+      @header.rect = Tuile::Rect.new(0, 0, width, 1)
+      @status.rect = Tuile::Rect.new(0, height - 1, width, 1)
+      body_height = [height - 2, 0].max
+      half = width / 2
+      @left_window.rect = Tuile::Rect.new(0, 1, half, body_height)
+      @right_window.rect = Tuile::Rect.new(half, 1, width - half, body_height)
     end
 
     private

data/examples/hello_world.rb

@@ -37,7 +37,7 @@ window.content = Tuile::Component::Label.new("Hello, world!")
 status = Tuile::Component::Label.new
 render_status = -> { status.text = "q #{screen.theme.fg(:hint, "quit")}" }
 render_status.call
-status.on_theme_changed = render_status
+status.on_theme_changed << render_status
 
 # One row for the status line, everything else to the window.
 root = Tuile::Component::Layout::Vertical.new