tuile 0.15.0 → 0.17.0

data/lib/tuile/screen_pane.rb

@@ -8,12 +8,12 @@ module Tuile
   # {#content} and the {#popups} stack. Putting them under a single Component
   # parent gives focus traversal a real root, makes {Component#attached?} a
   # one-liner, and lets popup-focus repair fall out of the standard
-  # {Component#on_child_removed} hook.
+  # {Component#handle_child_removed} hook.
   #
   # The pane owns no chrome of its own — no status bar, no reserved row.
   # {#content} gets the full pane rect, and an app that wants a status line
   # builds one into its own layout and drives it from
-  # {Screen#on_focus_changed=} (`D_status_bar`).
+  # {Screen#on_focus_changed} (`D_status_bar`).
   #
   # The pane is not a {Component::Layout}: popups deliberately overlap content
   # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
@@ -27,6 +27,10 @@ module Tuile
       # user was, instead of falling through to {#content} and getting
       # cascaded to the first focusable child.
       @popup_prior_focus = {}
+      # Where each open popup wants to be, and the anchor rect its last
+      # placement used (`:lost` once the anchor went away) — see #relayout.
+      @placements = {}.compare_by_identity
+      @placed_anchors = {}.compare_by_identity
     end
 
     # @return [Component, nil] the tiled content component.
@@ -52,14 +56,13 @@ module Tuile
       remove_child(@content) unless @content.nil?
       @content = content
       add_child(content, at: 0) # the tiled layer paints beneath everything else
-      layout
     end
 
-    # Adds an overlay and invalidates it for repaint. A {Component::Popup} is
-    # centered and grabs focus; a bare {Component::Overlay} is left wherever
-    # the caller positioned it and does *not* take focus, so the component that
-    # was focused keeps the cursor and keeps receiving keys — the overlay
-    # floats above the content, driven from app code.
+    # Adds an overlay at `placement` and invalidates it for repaint; the next
+    # settle gives it its rect. A {Component::Popup} grabs focus; a bare
+    # {Component::Overlay} does *not*, so the component that was focused keeps
+    # the cursor and keeps receiving keys — the overlay floats above the
+    # content, driven from app code.
     #
     # The *whole subtree* is invalidated, not just the overlay wrapper (which
     # paints nothing on its own): a reopened popup may land on cells that the
@@ -67,19 +70,46 @@ module Tuile
     # last time its content components won't re-invalidate themselves — so
     # without this the overlay's contents would stay blank on reopen.
     # @param window [Component::Overlay] any overlay, modal or not.
+    # @param placement [Component::Overlay::Placement, nil] where it wants to
+    #   be; `nil` takes its {Component::Overlay#default_placement}.
+    # @raise [TypeError] if `placement` does not include
+    #   {Component::Overlay::Placement}.
     # @return [void]
-    def add_popup(window)
+    def add_popup(window, placement = nil)
       raise TypeError, "expected Overlay, got #{window.inspect}" unless window.is_a? Component::Overlay
       raise ArgumentError, "#{window} already has a parent #{window.parent}" unless window.parent.nil?
 
+      placement ||= window.default_placement
+      check_placement(placement)
       @popup_prior_focus[window] = screen.focused
+      @placements[window] = placement
       @popups << window
       add_child(window) # appended: popups paint over the tiled content
-      if window.modal?
-        window.center
-        screen.focused = window
-      end
-      window.on_tree { |c| screen.invalidate(c) }
+      screen.focused = window if window.modal?
+      window.walk_tree { |c| screen.invalidate(c) }
+    end
+
+    # @param popup [Component::Overlay] an open popup.
+    # @return [Component::Overlay::Placement, nil] where it wants to be; `nil`
+    #   if it isn't open here.
+    def placement(popup) = @placements[popup]
+
+    # Moves an open popup; it takes the new rect on the next settle.
+    # {Component::Overlay#placement=} is the usual way in.
+    # @param popup [Component::Overlay] an open popup.
+    # @param placement [Component::Overlay::Placement] where it wants to be.
+    # @raise [ArgumentError] if `popup` isn't open on this pane.
+    # @raise [TypeError] if `placement` does not include
+    #   {Component::Overlay::Placement}.
+    # @return [void]
+    def constrain(popup, placement)
+      raise ArgumentError, "#{popup} is not an open popup on this pane" unless has_popup?(popup)
+
+      check_placement(placement)
+      return if @placements[popup] == placement
+
+      @placements[popup] = placement
+      invalidate_layout
     end
 
     # Removes a popup. If the popup held focus, focus shifts to the now-topmost
@@ -91,6 +121,8 @@ module Tuile
       raise Tuile::Error, "#{window} is not an open popup on this pane" unless @popups.delete(window)
 
       prior = @popup_prior_focus.delete(window)
+      @placements.delete(window)
+      @placed_anchors.delete(window)
       @removing_popup_prior = prior
       remove_child(window)
       # Runs after the detach, so a prior pointing *inside* the removed popup is
@@ -102,7 +134,7 @@ module Tuile
       @removing_popup_prior = nil
     end
 
-    # Unmounts everything: each child is detached — firing {Component#on_detached}
+    # Unmounts everything: each child is detached — firing {Component#handle_detached}
     # down its subtree — and every slot is emptied. Terminal; the pane isn't
     # reusable afterwards, and {Screen#close} is its only caller.
     #
@@ -113,11 +145,13 @@ module Tuile
     # components, which is the desync the tree API exists to prevent.
     # @return [void]
     def detach_all
-      screen.focused = nil # …so the focus repair in on_child_removed has nothing to do
+      screen.focused = nil # …so the focus repair in handle_child_removed has nothing to do
       children.dup.each { detach_child(_1) }
       @content = nil
       @popups.clear
       @popup_prior_focus.clear
+      @placements.clear
+      @placed_anchors.clear
     end
 
     # @param window [Component]
@@ -131,33 +165,43 @@ module Tuile
     #   content without capturing input.
     def modal_popup = @popups.reverse_each.find(&:modal?)
 
-    # Re-lays out children whenever the pane's own rect changes.
-    # @param new_rect [Rect]
-    # @return [void]
-    def rect=(new_rect)
-      super
-      layout
-    end
+    # The root of the current **key scope**: the topmost modal popup when one
+    # is open, else the tiled {#content}. Keys bubble up to it and no further,
+    # a paste reaches only a focus chain inside it, and Tab cycles only the
+    # stops beneath it — so a component outside it is one the keyboard cannot
+    # reach at all. The mouse resolves against a *point* instead
+    # ({#mouse_root_at}).
+    # @return [Component, nil] nil when the pane holds neither.
+    def key_scope = modal_popup || @content
 
     # Gives {#content} the whole pane rect — the pane reserves nothing for
-    # itself. Each popup re-resolves its {Component::Popup#declared_size} against the new
-    # screen via {Component::Popup#reposition} — so a {Fraction} size tracks
-    # resize — repositioning itself (modal popups recenter; non-modal overlays
-    # keep the top-left their owner assigned).
+    # itself — and each popup the rect its placement asks for, in stacking
+    # order, so a submenu is placed after the panel it hangs from.
+    #
+    # Re-running it moves nothing that stood still: a placement is a rule, so
+    # a second popup opening re-derives the first one's rect unchanged.
+    #
+    # An empty pane collapses every popup rather than placing it — an `At` rect
+    # would otherwise stand in a pane with no cells — and has no `return if
+    # rect.empty?` guard, which would strand the content at its last rect
+    # (`D_empty_ancestor`).
     # @return [void]
-    def layout
-      return if rect.empty?
-
-      @content&.rect = rect
-      @popups.each(&:reposition)
+    def relayout
+      @content&.rect = local_rect
+      if rect.empty?
+        @popups.each { _1.rect = Rect.new(0, 0, 0, 0) }
+      else
+        @popups.each { place(_1) }
+      end
     end
 
     # Pane paints nothing itself; its children paint over the entire rect.
+    # @param _canvas [Canvas] see {Component#repaint}.
     # @return [void]
-    def repaint; end
+    def repaint(_canvas); end
 
     # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
-    # the first component whose `handle_key` returns true wins.
+    # the first component whose `handle_key?` returns true wins.
     #
     # Bubbling stops at the *scope* root: the topmost *modal* popup when one is
     # open, else the tiled {#content}. Focus that is nil or sits outside the
@@ -173,8 +217,8 @@ module Tuile
     # hijacked).
     # @param key [String]
     # @return [Boolean] true if the key was handled.
-    def handle_key(key)
-      scope = modal_popup || @content
+    def handle_key?(key)
+      scope = key_scope
       return false if scope.nil?
 
       bubble_key(key, scope)
@@ -182,38 +226,39 @@ module Tuile
 
     # Delivers pasted text to {Screen#focused} — and to nobody else.
     #
-    # Scoped exactly like {#handle_key} (focus that is nil or sits outside the
+    # Scoped exactly like {#handle_key?} (focus that is nil or sits outside the
     # modal scope receives nothing, which is what keeps a popup modal) but
     # **not bubbled**: an ancestor is never offered a paste its descendant
     # declined, and unhandled text is dropped. Why keys bubble and pastes
     # don't: `D_bracketed_paste`.
     # @param text [String]
-    # @return [Boolean] true if the focused component consumed it.
+    # @return [void]
     def handle_paste(text)
-      scope = modal_popup || @content
-      return false if scope.nil?
+      scope = key_scope
+      return if scope.nil?
 
       chain = focus_chain(scope)
-      return false if chain.nil?
+      return if chain.nil?
 
       chain.first.handle_paste(text)
     end
 
-    # Mouse events check popups in reverse stacking order (topmost first), and
-    # fall through to content only when no popup is hit *and* no modal popup is
-    # open. This preserves modal click-blocking — an open modal eats clicks
-    # even outside its rect — while a non-modal overlay blocks nothing: clicks
-    # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
-    # content beneath.
-    #
-    # A left click also *dismisses* the open popups it landed outside of that
-    # asked for it ({Component::Overlay#close_on_outside_click?}). That is a
-    # second thing happening on a click, but not a second dispatch: the click is
-    # still delivered exactly once, down one chain, and a dismissed popup is
+    # Where {Mouse::Router} starts its walk for a pointer at `point`: the
+    # topmost popup containing it, else {#content} — unless a modal popup is
+    # open, which eats the event even outside its rect. A non-modal overlay
+    # blocks nothing: a point outside it reaches the content beneath.
+    # @api private
+    # @param point [Point]
+    # @return [Component, nil]
+    def mouse_root_at(point) = popup_at(point) || (@content if modal_popup.nil?)
+
+    # Runs the press delivery in the block, then *dismisses* the open popups a
+    # left press landed outside of that asked for it
+    # ({Component::Overlay#close_on_outside_click?}). A dismissed popup is
     # closed rather than told.
     #
     # "Outside" is measured against the {Component::Overlay#owner} chain, not
-    # against one rect and not against stacking order: the popup the click hit
+    # against one rect and not against stacking order: the popup the press hit
     # is kept, and so is every popup that one *belongs to*, transitively. That
     # is what stops a dialog being dismissed by a click on a dropdown its own
     # field opened, and a menu cascade being dismissed by a click on one of its
@@ -223,10 +268,10 @@ module Tuile
     #
     # Two halves of the ordering are load-bearing, and both are specced:
     #
-    # - **Snapshot before routing.** A popup the delivered click *opens* must
+    # - **Snapshot before the block.** A popup the delivered press *opens* must
     #   not be in the set (it would immediately dismiss itself — every
     #   {Component::Select} would be unopenable by mouse).
-    # - **Close after routing.** A widget toggling its own overlay from a click
+    # - **Close after the block.** A widget toggling its own overlay from a press
     #   on its face closes it during delivery, and {Component::Popup#close} is
     #   idempotent, so the dismissal no-ops. Close *first* and the widget sees
     #   a shut overlay and reopens it — a Select's dropdown could then never be
@@ -234,19 +279,19 @@ module Tuile
     #
     # The snapshot is a fresh array for a third reason: a handler may close
     # further popups, and `@popups` must not be mutated mid-iteration.
-    # @param event [MouseEvent]
+    # @api private
+    # @param point [Point]
+    # @param left [Boolean] whether the press was the left button; no other
+    #   button dismisses.
+    # @yield the press delivery.
     # @return [void]
-    def handle_mouse(event)
-      hit = @popups.reverse_each.find { _1.rect.contains?(event.point) }
-      dismissable = event.button == :left ? @popups - kept_by(hit) : []
-
-      clicked = hit || (@content if modal_popup.nil?)
-      clicked&.handle_mouse(event)
-
+    def dismissing_popups_outside(point, left:)
+      dismissable = left ? @popups - kept_by(popup_at(point)) : []
+      yield
       dismissable.each { _1.close if _1.close_on_outside_click? }
     end
 
-    # Focus repair when a child detaches. Default {Component#on_child_removed}
+    # Focus repair when a child detaches. Default {Component#handle_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
     # Instead, route focus to the first interactable widget in the now-topmost
     # modal popup; falling back to the focus snapshotted when this popup was opened
@@ -259,7 +304,7 @@ module Tuile
     # `q`/ESC still has somewhere to dispatch from.
     # @param child [Component]
     # @return [void]
-    def on_child_removed(child)
+    def handle_child_removed(child)
       return unless attached?
 
       f = screen.focused
@@ -282,6 +327,75 @@ module Tuile
 
     private
 
+    # Rejects a non-placement where the app named it, rather than mid-pass: the
+    # layout is deferred, so the `NoMethodError` from a missing `rect_for` would
+    # otherwise surface a turn later, under this file's backtrace.
+    # @param placement [Object]
+    # @raise [TypeError] unless it includes {Component::Overlay::Placement}.
+    # @return [void]
+    def check_placement(placement)
+      return if placement.is_a?(Component::Overlay::Placement)
+
+      raise TypeError, "#{placement.class} must include Tuile::Component::Overlay::Placement"
+    end
+
+    # A placement's {Component::Overlay::Placement#anchor} in screen
+    # coordinates: a `Rect` passes through, a component resolves while it is on
+    # screen, and `nil` means either unanchored or gone — {#place} tells those
+    # apart by whether an anchor was declared at all.
+    # @param anchor [Component, Rect, nil]
+    # @return [Rect, nil]
+    def resolve_anchor(anchor)
+      return anchor if anchor.nil? || anchor.is_a?(Rect)
+
+      ComponentUtil.effectively_visible?(anchor) ? anchor.absolute_extent_rect : nil
+    end
+
+    # @param popup [Component::Overlay]
+    # @return [void]
+    def place(popup)
+      placement = @placements.fetch(popup)
+      anchor = placement.anchor
+      anchor_rect = resolve_anchor(anchor)
+      unless anchor.nil?
+        return lose_anchor(popup) if anchor_rect.nil?
+
+        @placed_anchors[popup] = anchor_rect
+      end
+      popup.rect = placement.rect_for(popup, rect.size, anchor_rect)
+    end
+
+    # Leaves a popup whose anchor was detached or hidden at its last rect. It
+    # warns, once, because closing the popup is its owner's job and an owner
+    # that forgot leaves it floating over nothing.
+    # @param popup [Component::Overlay]
+    # @return [void]
+    def lose_anchor(popup)
+      return if @placed_anchors[popup] == :lost
+
+      @placed_anchors[popup] = :lost
+      Tuile.logger.warn("#{popup} lost its anchor; left where it was — close it when the anchor goes")
+    end
+
+    # Re-marks the pane when an anchored popup's anchor now resolves elsewhere
+    # than where its last placement read it. {Screen#flush_layout} asks once
+    # its drain is empty, because this pane's pass runs *before* the content an
+    # anchor sits in, so a settle that moved the content handed the pass a
+    # stale anchor. Anchors in `lib/` converge in one more round — the content
+    # never moves for a popup, and a cascade anchors to a `Rect` — but a popup
+    # anchored inside another takes one round per level.
+    # @return [Boolean] whether it marked, so the screen drains again.
+    def remark_moved_anchors
+      return false if rect.empty? # #relayout collapses rather than places then, so nothing records
+
+      moved = @popups.any? do |popup|
+        anchor = @placements[popup].anchor
+        !anchor.nil? && (resolve_anchor(anchor) || :lost) != @placed_anchors[popup]
+      end
+      invalidate_layout if moved
+      moved
+    end
+
     # The overlays a click counts as landing *inside*: the one it hit, plus
     # every overlay that one belongs to, up the {Component::Overlay#owner}
     # chain. An owner is any component, so it is resolved to the overlay
@@ -301,6 +415,10 @@ module Tuile
       kept
     end
 
+    # @param point [Point]
+    # @return [Component::Overlay, nil] the topmost popup containing `point`.
+    def popup_at(point) = @popups.reverse_each.find { _1.rect.contains?(point) }
+
     # @param component [Component, nil]
     # @return [Component::Overlay, nil] `component` itself when it is an
     #   overlay, else the nearest overlay above it, else nil.
@@ -321,7 +439,7 @@ module Tuile
       chain = focus_chain(scope)
       return false if chain.nil?
 
-      chain.each { |c| return true if c.handle_key(key) }
+      chain.each { |c| return true if c.handle_key?(key) }
       false
     end
 
@@ -350,7 +468,7 @@ module Tuile
     def first_tab_stop_or_root(root)
       return nil if root.nil? || !root.visible?
 
-      root.on_shown_tree { |c| return c if c.tab_stop? }
+      root.walk_shown_tree { |c| return c if c.tab_stop? }
       root
     end
   end

data/lib/tuile/strict_layout.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The stale-rect diagnostic: a {Component#rect} read taken while an ancestor
+  # still owes a {Component#relayout} says so, instead of handing back the
+  # previous pass's rectangle in silence. **On wherever a {FakeScreen} is the
+  # installed screen** — a spec suite needs no setup to get it — and off in an
+  # app, which {Tuile.strict_layout} overrides either way:
+  #
+  #   holder.constrain(pane, Rect.new(0, 0, 100, 26))
+  #   pane.left.rect        # => Tuile::Error: read the rect of #<Tuile::Component::Label
+  #                         #    rect=(0,0 80x50)> while #<TwoPane rect=(0,0 100x26)> owes a
+  #                         #    relayout … at spec/two_pane_spec.rb:42
+  #
+  # `:warn` logs the same line to {Tuile.logger} and hands the rectangle over,
+  # for watching a running app; `:raise` is the default and what a spec wants,
+  # since the backtrace names the read and a suite that never set a logger
+  # would see nothing at all. For the read that is pre-settle *on purpose*,
+  # {Tuile.without_strict_layout}.
+  #
+  # Reading `size`, `width`, `height`, `local_rect`, `absolute_rect` or
+  # `to_screen` reports too — they all go through the one reader.
+  #
+  # **Only reads the app makes are reported** ({PLUMBING}): a read `lib/` makes
+  # on the app's behalf mid-handler is not the app's to fix.
+  #
+  # == Implementation details
+  #
+  # {Tuile.strict_layout=} and {FakeScreen} prepend this module into
+  # {Component}, so `rect` stays the bare `attr_reader` — the hottest read in
+  # the toolkit — in every process that never asks. Nothing unprepends; turning
+  # the mode off leaves the check inert. See `D_strict_layout`.
+  module StrictLayout
+    # Where the gem's own frames live, so the site the message names is the
+    # app's — `to_screen` and the `size` / `width` / `height` trio all read
+    # `rect` from inside `component.rb`.
+    # @return [String]
+    LIB_DIR = File.expand_path("..", __dir__)
+
+    # The thread-local marking a report in progress: {Component#inspect} prints
+    # the rect, so building the message re-enters `rect` on the very component
+    # that is being complained about.
+    # @return [Symbol]
+    REPORTING = :tuile_strict_layout_reporting
+
+    # The readers that only forward to `rect`. A frame of one of these between
+    # the read and the app's own code carries no decision of the framework's, so
+    # the read still counts as the app's.
+    # @return [Array<String>]
+    PLUMBING = %w[rect size width height local_rect local_extent_rect absolute_rect absolute_extent_rect
+                  to_screen to_local].freeze
+
+    class << self
+      # Makes {Component#rect} consult {Tuile.strict_layout} — idempotent, and
+      # permanent for the process.
+      # @return [void]
+      def install = Component.prepend(self)
+
+      # Reports `component`'s rect read as stale, the way `mode` asks for.
+      #
+      # @param component [Component] the component whose rect was read.
+      # @param ancestor [Component] the ancestor owing the relayout.
+      # @param mode [Symbol] `:raise` or `:warn`.
+      # @raise [Error] in `:raise` mode, unless the read was the framework's own.
+      # @return [void]
+      def report(component, ancestor, mode)
+        return unless app_read?
+
+        message = message_for(component, ancestor)
+        raise Error, message if mode == :raise
+
+        Tuile.logger.warn(message)
+      end
+
+      private
+
+      # @param component [Component]
+      # @param ancestor [Component]
+      # @return [String]
+      def message_for(component, ancestor)
+        Thread.current[REPORTING] = true
+        "Tuile: read the rect of #{component.inspect} while #{ancestor.inspect} owes a relayout — " \
+          "that rectangle is the previous pass's. Call flush_layout before reading it (a spec), or " \
+          "read it after the next event (an app)#{site}"
+      ensure
+        Thread.current[REPORTING] = false
+      end
+
+      # Whether the app asked the question rather than the framework on its
+      # behalf: the frames between the read and the first one outside the gem
+      # are {PLUMBING} and nothing else.
+      # @return [Boolean]
+      def app_read?
+        frames.each do |frame|
+          return true unless frame.path.start_with?(LIB_DIR)
+          return false unless PLUMBING.include?(frame.base_label)
+        end
+        false
+      end
+
+      # @return [String] ` at <path>:<line>` for the frame that made the read,
+      #   or `""` when there is none outside the gem.
+      def site
+        frame = frames.find { !_1.path.start_with?(LIB_DIR) }
+        frame.nil? ? "" : " at #{frame.path}:#{frame.lineno}"
+      end
+
+      # The stack above this file, asked from wherever in it — dropping our own
+      # frames by path rather than by a `caller_locations` offset, which would
+      # be two different numbers and would drift on any refactor here.
+      # @return [Array<Object>] `Thread::Backtrace::Location`s.
+      def frames = caller_locations.drop_while { _1.path == __FILE__ }
+    end
+
+    # {Component#rect}, reporting first when it is about to answer the previous
+    # pass's rectangle.
+    # @return [Rect]
+    def rect
+      mode = Tuile.strict_layout
+      if mode && !Thread.current[REPORTING]
+        ancestor = stale_layout_ancestor
+        StrictLayout.report(self, ancestor, mode) unless ancestor.nil?
+      end
+      super
+    end
+  end
+end