tuile 0.16.0 → 0.17.0

data/lib/tuile/component.rb

@@ -11,16 +11,20 @@ module Tuile
   #
   # == Handlers and listener slots
   #
-  # Two families, told apart by the `=`:
+  # Two families — `handle_` is the override point, `on_` the listener slot:
   #
   #   class Trimmed < Component::TextField
   #     def handle_blur                  # handle_ — the override point
   #       super
-  #       self.text = text.strip
+  #       self.value = text.strip
   #     end
   #   end
   #
-  #   label.on_theme_changed = -> { … }   # on_…= — the listener slot
+  #   label.on_theme_changed { … }        # on_… — the listener slot, a {Listeners}
+  #
+  # A slot holds *many* listeners and has no setter: register with the reader,
+  # remove with {Listeners#remove}, and nothing you add can displace what the
+  # widget or another app wired there.
   #
   # **What a handler returns is per hook**, declared in its own rdoc. Only the
   # ones a dispatcher routes answer at all — {#handle_key?},
@@ -28,27 +32,27 @@ module Tuile
   # took this, stop bubbling". The rest, {#handle_paste} included, return `void`.
   #
   # An override calls `super`, even where the base body is empty: that is what
-  # lets a hook grow an `on_foo=` slot without breaking you. The one carve-out is
+  # lets a hook grow an `on_foo` slot without breaking you. The one carve-out is
   # {#handle_child_removed}, whose base does real work and whose overrides
   # replace it. `D_handler_naming` carries the argument.
   class Component
     extend Final
+    extend Listeners::Declare
 
     # Each method's own rdoc says what an override would break; `D_final_tree`
     # carries the full argument.
     final :children, :parent, :parent=, :add_child, :remove_child, :detach_child,
-          :effective_bg_color
+          :bg
 
     def initialize
       Component.verify_final!(self.class)
       @rect = Rect.new(0, 0, 0, 0)
       @visible = true
       @active = false
-      @on_theme_changed = nil
-      @on_locale_changed = nil
-      @bg_color = nil
+      @bg = ComponentBackground.new(self)
       @children = []
       @id = nil
+      @layout_dirty = false
     end
 
     # A tag for finding this component again — nothing paints it, and the
@@ -74,7 +78,17 @@ module Tuile
       @id = new_id
     end
 
-    # @return [Rect] the rectangle the component occupies on screen.
+    # The rectangle the component occupies **inside its parent**: `(0, 0)` is
+    # the parent's top-left, not the screen's. {#absolute_rect} is where that
+    # lands on screen, and {#local_rect} is this same rectangle with the
+    # position taken out.
+    #
+    # **Layout is deferred, so a rect read in the same turn that dirtied it is
+    # the *previous* pass's** — a plausible rectangle, not zeros.
+    # {#flush_layout} brings it up to date (`D_deferred_layout`),
+    # {#rect_stale?} answers whether it is one, and {Tuile.strict_layout} makes
+    # every such read say so.
+    # @return [Rect]
     attr_reader :rect
 
     # The three readers below report the geometry a parent *assigned*, as
@@ -101,7 +115,9 @@ module Tuile
     #
     # It always sits at {#rect}'s top-left — which is why this is a {Size} and
     # not a {Rect}: an offset extent is not merely unsupported, it is
-    # unrepresentable. Use {#extent_rect} where coordinates are wanted.
+    # unrepresentable. Use {#local_extent_rect} or {#absolute_extent_rect} where
+    # coordinates are wanted — there is no parent-space form, because nothing
+    # asks the question in that space.
     #
     # **`nil` is not the same as `rect.size`.** `nil` says "I have not declared
     # what I paint, so clear everything before I do", which is what a
@@ -116,8 +132,9 @@ module Tuile
     # so {#rect} still means exactly what the parent assigned (`D_extent`). Three
     # things read it, all of them this component or the framework painting it:
     # {#clear_outside_extent} blanks the dead tail, {Mouse::Router} hit-tests
-    # against it so a click on that tail doesn't activate the widget, and a
-    # dropdown anchors under it rather than under unused space.
+    # against {#local_extent_rect} so a click on that tail doesn't activate the
+    # widget, and a dropdown anchors under {#absolute_extent_rect} rather than
+    # under unused space.
     #
     # **An override promises to paint the extent in full**, so `super` in
     # {#repaint} blanks only what is outside it. The arithmetic is each widget's
@@ -126,36 +143,198 @@ module Tuile
     # @return [Size, nil]
     def extent = nil
 
-    # {#extent} placed at {#rect}'s top-left, for the consumers that need
-    # coordinates: `extent_rect.contains?(point)` in {Mouse::Router}, and
-    # the anchor a dropdown hangs from. Total — an undeclared {#extent} yields
-    # the whole {#rect}, so a generic caller never sees `nil`.
+    # {#rect} with the position taken out: the same size at `(0, 0)`.
+    #
+    # **Two things live in these coordinates**, and that is the whole point of
+    # them being one space: what this component *paints* ({Screen#canvas_for}
+    # puts the canvas here), and what its children's {#rect}s are measured in.
+    # So a container divides `local_rect` among its children and blanks its own
+    # gaps in the very same numbers:
+    #
+    #   private def relayout
+    #     half = width / 2                       # no `rect.left +` anywhere:
+    #     left.rect  = Rect.new(0, 0, half, height)
+    #     right.rect = Rect.new(half, 0, width - half, height)
+    #   end
+    #
+    # @return [Rect]
+    def local_rect = Rect.new(0, 0, rect.width, rect.height)
+
+    # {#extent} at `(0, 0)`, {#local_rect}'s counterpart — what
+    # {#clear_inside_extent} blanks and what {Mouse::Router} hit-tests. Total:
+    # an undeclared {#extent} yields {#local_rect}, so a generic caller never
+    # sees `nil`.
     # @return [Rect]
-    def extent_rect
+    def local_extent_rect
       e = extent
-      e.nil? ? rect : Rect.new(rect.left, rect.top, e.width, e.height)
+      e.nil? ? local_rect : Rect.new(0, 0, e.width, e.height)
     end
 
-    # Sets new position of the component. This is the absolute component
-    # positioning on screen, not a relative positioning relative to component's
-    # {#parent}.
+    # {#rect} in **screen** coordinates — every ancestor's offset summed in.
+    # The form the three consumers outside this component's own frame need: the
+    # {Canvas#origin} {Screen#canvas_for} builds, an overlay's anchor (an
+    # overlay hangs off {ScreenPane}, so it shares no offset with its driver),
+    # and a spec clicking a component by where it sits.
     #
-    # The component must not stick outside of {#parent}'s rect.
+    # Derived on every call and never cached — a parent may move this subtree
+    # between two reads, and nothing announces it (`D_relative_rect`).
+    # @return [Rect]
+    def absolute_rect = rect.at(to_screen(Point::ZERO))
+
+    # {#local_extent_rect} in screen coordinates, {#absolute_rect}'s
+    # counterpart — what a dropdown anchors against.
+    # @return [Rect]
+    def absolute_extent_rect = local_extent_rect.at(to_screen(Point::ZERO))
+
+    # Converts a point in *this component's own* coordinates — the ones it
+    # paints in, the ones a {Mouse::Event} reaches it in — to screen
+    # coordinates, by walking up and adding each ancestor's offset.
+    #
+    #   # a strip anchoring a panel under one of its own segments
+    #   Rect.new(0, 0, width, 1).at(to_screen(Point.new(column, 0)))
+    #
+    # Iterative and summing into two locals rather than recursing through a
+    # {Point} per level: this runs once per component per repaint, from
+    # {Screen#canvas_for}.
+    # @param point [Point] in this component's coordinates.
+    # @return [Point] in screen coordinates.
+    def to_screen(point)
+      x = point.x
+      y = point.y
+      node = self
+      until node.nil?
+        x += node.rect.left
+        y += node.rect.top
+        node = node.parent
+      end
+      Point.new(x, y)
+    end
+
+    # {#to_screen}'s inverse: a screen point in this component's own
+    # coordinates. The result may be negative or past {#size} — a point outside
+    # the component converts perfectly well, which is what a grabbed component's
+    # {Mouse::DragEvent} relies on.
+    # @param point [Point] in screen coordinates.
+    # @return [Point] in this component's coordinates.
+    def to_local(point)
+      x = point.x
+      y = point.y
+      node = self
+      until node.nil?
+        x -= node.rect.left
+        y -= node.rect.top
+        node = node.parent
+      end
+      Point.new(x, y)
+    end
+
+    # Places the component **inside its parent**: `(0, 0)` is the parent's
+    # top-left, so a container divides its own {#local_rect} and never adds its
+    # own position in. {#absolute_rect} is where the result lands on screen.
+    #
+    # A component that sticks outside its parent's {#local_rect}, or paints
+    # outside this rectangle, is cut to it — {Screen#canvas_for} bounds every
+    # component by its own rect and every ancestor's (`D_clip`). Overrunning is
+    # still a bug; it now shows as truncation rather than as a corrupt neighbour.
+    #
+    # The component is invalidated and will paint over the new rectangle, and
+    # so is its parent, which owns the cells the old position vacated.
+    #
+    # **The children do not move yet**: this only marks a {#relayout}, so a
+    # child's rect read back in the same turn is still the previous pass's —
+    # {#flush_layout} first.
     #
-    # The component is invalidated and will paint over the new rectangle. It is
-    # parent's job to paint over the old component position.
+    # **Only the parent's {#relayout} may call this**, and it raises from
+    # anywhere else, a component with no parent included. To move a child,
+    # change what its parent places it by — {Layout::Absolute#constrain},
+    # {Layout::Box#constrain}, {Component::Overlay#placement=} — and to size a
+    # tree that has no screen, hold it in a {Layout::Absolute}:
+    #
+    #   holder = Component::Layout::Absolute.new
+    #   holder.add(tree, Rect.new(0, 0, 40, 10))
+    #   holder.flush_layout
+    #
+    # A subclass reacts to a new rect in {#handle_rect_changed}; it cannot
+    # override this, because a `protected` override is callable only from its
+    # own class, and the parent calling it is not one.
     # @param new_rect [Rect] new position. Does nothing if the new rectangle is
     #   the same as the old one.
+    # @raise [Tuile::Error] unless the parent's {#relayout} is running.
     def rect=(new_rect)
       raise TypeError, "expected Rect, got #{new_rect.inspect}" unless new_rect.is_a? Rect
+
+      LayoutPass.check(self)
+      LayoutPass.note_placement(self)
       return if @rect == new_rect
 
-      prev_width = @rect.width
+      old_rect = @rect
       @rect = new_rect
-      handle_width_changed if prev_width != new_rect.width
+      handle_rect_changed(old_rect)
       invalidate
+      # Nothing else blanks the cells the old rect vacated — the same reason
+      # {#visible=} invalidates the parent.
+      parent&.invalidate
+      invalidate_layout
+    end
+    protected :rect=
+
+    # Runs every {#relayout} this component's *tree* owes, so its rects are
+    # current — the force-now that makes a detached tree measurable:
+    #
+    #   layout = Component::Layout::Vertical.new   # no Screen in the process
+    #   layout.add(label, Fixed[1])
+    #   layout.rect = Rect.new(0, 0, 20, 10)
+    #   layout.flush_layout
+    #   label.rect                                 # => Rect(0, 0, 20, 1)
+    #
+    # Attached, {Screen#dispatch} already flushes after every event, so ask for
+    # this by hand only to read a rect in the *same* turn that dirtied it —
+    # what Swing spells `validate()` and Tk `update idletasks`.
+    #
+    # **Overwhelmingly that means a spec**: an app mutates and lets the settle
+    # run, so a `flush_layout` in app code is usually a sign the *read* wants
+    # deferring instead.
+    #
+    # == Implementation details
+    #
+    # The whole tree, never this subtree, whichever end it is asked from: a
+    # pending ancestor pass would overwrite whatever a narrower one wrote.
+    # Attached that is {Screen#flush_layout}; detached it is {LayoutPass.drain}
+    # from {#root}, the same fixpoint the screen runs.
+    # @raise [Tuile::Error] when the tree has not settled after
+    #   {LayoutPass::MAX_ROUNDS} rounds — a relayout feeding its own input — or
+    #   when called from inside a {#relayout}.
+    # @return [void]
+    def flush_layout
+      return screen.flush_layout if attached?
+
+      LayoutPass.refuse_nested
+      LayoutPass.drain(root)
     end
 
+    # Whether this container owes a {#relayout} — that its *children*'s rects
+    # are out of date.
+    #
+    # **It says nothing about this component's own {#rect}**, which no pass of
+    # its own touches: the flag that makes *this* rect stale sits on the parent
+    # that assigns it, and {#rect_stale?} is that question asked from here.
+    # Survives detaching, so {#handle_attached} can hand the mark to the {Screen}.
+    # @return [Boolean]
+    def layout_dirty? = @layout_dirty
+
+    # Whether {#rect} is the *previous* pass's rectangle, because some ancestor
+    # owes a {#relayout} and that pass reassigns every rect below it — or is
+    # running it right now and has not reached this branch yet.
+    #
+    #   holder.constrain(pane, Rect.new(0, 0, 100, 26))
+    #   pane.left.rect_stale?   # => true — `pane.left.rect` is still the old half
+    #
+    # {#flush_layout} makes it false; {Tuile.strict_layout} reports every read
+    # taken while it is true. One walk to {#root} per call, which is why no
+    # framework read consults it outside strict mode.
+    # @return [Boolean]
+    def rect_stale? = !stale_layout_ancestor.nil?
+
     # This component's own flag — **not** whether the user can see it, which
     # also depends on its ancestors: a shown field inside a hidden panel
     # answers `true`.
@@ -185,7 +364,9 @@ module Tuile
     #   {#handle_child_removed}), and does not hand it back on the way in.
     #
     # For "invisible but still occupying its space", use a
-    # {Component::Slot} with no content (`D_slots`).
+    # {Component::Slot} with no content (`D_slots`). The parent's own
+    # {#relayout} may flip it — before placing any child, or it runs twice
+    # ({#invalidate_layout}).
     # @param value [Boolean]
     # @raise [Tuile::Error] when the UI is locked, or always from
     #   {Component::Overlay#visible=}.
@@ -196,9 +377,12 @@ module Tuile
 
       screen.check_locked if attached?
       @visible = value
-      # `__send__` for the same reason `Screen#theme=` uses it: the hook is
-      # protected (`D_hook_visibility`).
-      parent&.__send__(:handle_child_visibility_changed, self)
+      # Both on the parent, because the child just vacated (or re-claimed) cells
+      # the parent owns *and* may have changed how it divides its space. A
+      # hidden component paints nothing itself, so nothing else would blank what
+      # it left behind.
+      parent&.invalidate
+      parent&.invalidate_layout
       repair_focus_after_hiding unless value
       walk_tree { |c| screen.invalidate(c) } if attached?
     end
@@ -212,35 +396,54 @@ module Tuile
       screen.focused = self
     end
 
-    # The states a background may be keyed by. Closed and framework-defined:
-    # a key is added when Tuile grows the state, never to let an app invent one.
-    # @return [Array<Symbol>]
-    BG_STATES = %i[normal active].freeze
-
-    # Assign to {#bg_color} to say "I contribute no background of my own" —
-    # resolution skips this component's {#default_bg_color} and takes whatever
-    # surrounds it. CSS's `background: inherit`, and the reason a widget with a
-    # well can be made to sit flush in a tinted panel:
+    # Asks whatever scrolls above to bring `rect` into view — "show me this",
+    # made by the component that wants to be seen, never polled for by a
+    # container:
+    #
+    #   row.scroll_to_visible                      # all of me
+    #   editor.scroll_to_visible(caret_row_rect)   # this much of me
     #
-    #   field.bg_color = Component::BG_INHERIT   # no well; take the pane's tint
+    # The request climbs the parent chain re-expressed a level at a time, so
+    # with nothing scrolling on the way it reaches the root and does nothing.
+    # {Screen#focused=} makes the no-argument call on every focus assignment,
+    # which is the whole of making Tab follow the view: a child scrolled out of
+    # sight keeps its rect, its keys and its tab stop (`D_empty_ancestor`).
     #
-    # Distinct from `nil`, which falls through to {#default_bg_color} *first*.
-    # There is deliberately no counterpart forcing the terminal default despite
-    # a tinted ancestor (`D_bg_inherit`).
-    # @return [Symbol]
-    BG_INHERIT = :inherit
+    # A container that scrolls overrides it, and the shape is the contract:
+    #
+    #   def scroll_to_visible(rect = local_extent_rect)
+    #     delta = ...                     # the minimum that makes rect visible
+    #     move_scroll_top_row_by(delta)
+    #     super(rect.moved_by(Point.new(0, -delta)))
+    #   end
+    #
+    # **The minimum** distance, so the far edge of the viewport is the one
+    # allowed to cut a child in half. And `super` takes the rect **where the
+    # scroll left it**, so an outer scroller is asked about cells that exist and
+    # nested scrollers settle inner-first.
+    #
+    # A hidden component raises, checked a level at a time as the request
+    # climbs — so it fails late: a scroller below a hidden ancestor has
+    # already scrolled.
+    # @param rect [Rect] in *this* component's coordinates; defaults to
+    #   {#local_extent_rect}, so a widget asks for what it paints.
+    # @raise [Tuile::Error] when this component or an ancestor is hidden.
+    # @return [void]
+    def scroll_to_visible(rect = local_extent_rect)
+      raise Tuile::Error, "#{self} is hidden; it cannot be scrolled into view" unless visible?
 
-    # @return [Color, Theme::Ref, Hash{Symbol => Color, Theme::Ref}, nil] this
-    #   component's own background — the value as set, so a {Theme::Ref} comes
-    #   back unresolved and a state map comes back a Hash; `nil` when unset, in
-    #   which case the component falls back to {#default_bg_color} and then to
-    #   its parent. {#effective_bg_color} is the resolved {Color} to paint.
-    attr_reader :bg_color
+      parent&.scroll_to_visible(rect.moved_by(self.rect.top_left))
+    end
+
+    # @return [Color, Theme::Ref, Hash{Symbol => Color, Theme::Ref}, Symbol, nil]
+    #   this component's own background — the value as set, so a {Theme::Ref}
+    #   comes back unresolved and a state map comes back a Hash; `nil` when
+    #   unset, in which case the widget's own well and then the parent answer.
+    def bg_color = @bg.color
 
     # Tints this component and every descendant that doesn't set its own
-    # background (they re-resolve via {#effective_bg_color}) — set it once on a
-    # container / {Component::Popup} to tint a whole subtree. Invalidates the
-    # subtree so it repaints.
+    # background — set it once on a container / {Component::Popup} to tint a
+    # whole subtree. Invalidates the subtree so it repaints.
     #
     # A {Theme::Ref} is re-resolved against the theme each paint, so it tracks
     # light/dark flips with no {#handle_theme_changed} hook; a {Color} is fixed:
@@ -248,9 +451,9 @@ module Tuile
     #   panel.bg_color = Theme.ref(:panel_bg)   # theme-tracked
     #   panel.bg_color = Color::GREY27          # fixed
     #
-    # A Hash keyed by {BG_STATES} gives a color per state — the shape a widget
-    # that highlights itself on focus needs, and the reason setting a flat color
-    # on one is a *choice* rather than a trap:
+    # A Hash keyed by {ComponentBackground::STATES} gives a color per state —
+    # the shape a widget that highlights itself on focus needs, and the reason
+    # setting a flat color on one is a *choice* rather than a trap:
     #
     #   field.bg_color = grey                            # flat: focused or not
     #   field.bg_color = { normal: grey, active: blue }  # the pair
@@ -258,27 +461,23 @@ module Tuile
     #                                                    # well, override focus
     #
     # A state whose key is absent is not answered here at all: resolution falls
-    # through to {#default_bg_color} and then to the parent, exactly as `nil`
+    # through to the widget's own well and then to the parent, exactly as `nil`
     # does. That is what makes the third line above mean what it reads as.
     #
     # This does *not* win over a validation error: {#error_bg_color} resolves
     # first, so tinting a panel cannot switch off the error well on the fields
-    # inside it.
+    # inside it. {ComponentBackground} carries the whole chain.
     #
     # @param color [Color, Theme::Ref, Hash, Symbol, Integer, Array<Integer>, nil]
-    #   a {Theme::Ref}, {BG_INHERIT}, a Hash keyed by {BG_STATES}, else a color
-    #   coerced via {Color.coerce}; `nil` unsets (fall through to
-    #   {#default_bg_color}, then the parent).
-    # @raise [ArgumentError] when a Hash carries a key outside {BG_STATES}.
+    #   a {Theme::Ref}, {ComponentBackground::INHERIT}, a state Hash, else a
+    #   color coerced via {Color.coerce}; `nil` unsets.
+    # @raise [ArgumentError] when a Hash carries a key outside
+    #   {ComponentBackground::STATES}.
     # @raise [KeyError] when a {Theme::Ref} names an absent custom token —
     #   validated eagerly at assignment, not deferred to paint.
     # @return [void]
     def bg_color=(color)
-      color = coerce_bg_color(color)
-      return if @bg_color == color
-
-      @bg_color = color
-      walk_tree { |c| screen.invalidate(c) } if attached?
+      @bg.color = color
     end
 
     # Repaints the component. The default does the bookkeeping most components
@@ -303,7 +502,7 @@ module Tuile
     # **The children are re-invalidated whether or not they tile.** A container
     # that paints nothing of its own can only redraw its area *through* them, so
     # a tiling container that skipped this would be a dead end in the cascade: an
-    # ancestor's `clear_background` wipes the whole ancestor rect — siblings and
+    # ancestor's background clear wipes the whole ancestor rect — siblings and
     # grandchildren included — and re-invalidates only its *direct* children, so
     # the notice has to keep travelling down or the cleared cells are never
     # repainted. Cheap by construction: repainting the same glyphs leaves
@@ -312,13 +511,25 @@ module Tuile
     # A container that skips `super` because it paints its own rect must still
     # call {#invalidate_children} — that is the half of this that cannot be
     # dropped.
+    #
+    # **Paint onto `canvas`, never onto {Screen#canvas} by name.** It arrives
+    # already loaded with this component's {ComponentBackground#effective}, so every write
+    # through it inherits; reach for the screen's own and inheritance silently
+    # stops (`D_canvas`).
+    #
+    # **The canvas paints in this component's own coordinates**: `(0, 0)` is {#rect}'s
+    # top-left, so `rect.left` has no place in a `repaint` — adding it lands
+    # the write at twice the offset, with nothing raising. {#local_rect} is
+    # the region argument to reach for; {Canvas} carries the two spaces.
+    # @param canvas [Canvas] the paint context, from {Screen#canvas_for}.
+    #   Required: a canvas carries state, so there is no default worth inventing.
     # @return [void]
-    def repaint
+    def repaint(canvas)
       return if rect.empty?
 
       unless children.any? && children_tile_rect?
-        clear_outside_extent
-        clear_inside_extent if extent && children.any?
+        clear_outside_extent(canvas)
+        clear_inside_extent(canvas) if extent && children.any?
       end
       invalidate_children
     end
@@ -364,7 +575,7 @@ module Tuile
     #   def handle_mouse_down?(event)
     #     return false unless event.button == :left
     #
-    #     @on_click&.call
+    #     on_click.fire(ClickEvent.new(source: self))
     #     true
     #   end
     #
@@ -531,23 +742,37 @@ module Tuile
     # @return [void]
     def handle_focus; end
 
-    # Optional zero-arg listener fired by the base {#handle_theme_changed} — the
-    # composition-style alternative to overriding the method, for apps that
-    # assemble stock components rather than subclass:
+    # What {#on_theme_changed} fires.
+    #
+    # @!attribute [r] source
+    #   @return [Component] the component whose theme changed.
+    ThemeChangedEvent = Data.define(:source) { include Tuile::Event }
+
+    # What {#on_locale_changed} fires.
     #
-    #   label.on_theme_changed = -> { label.text = render_status_line }
+    # @!attribute [r] source
+    #   @return [Component] the component whose locale changed.
+    LocaleChangedEvent = Data.define(:source) { include Tuile::Event }
+
+    # @!method on_theme_changed
+    #   Fired by the base {#handle_theme_changed} — the composition-style
+    #   alternative to overriding the method, for apps that assemble stock
+    #   components rather than subclass:
+    #
+    #     label.on_theme_changed { label.text = render_status_line }
     #
-    # @return [Proc, nil]
-    attr_accessor :on_theme_changed
+    #   @return [Listeners]
+    listener :on_theme_changed
 
-    # Optional zero-arg listener fired by the base {#handle_locale_changed} — the
-    # composition-style alternative to overriding the method, for an app that
-    # rendered a date or a number into a stock component:
+    # @!method on_locale_changed
+    #   Fired by the base {#handle_locale_changed} — the composition-style
+    #   alternative to overriding the method, for an app that rendered a date or
+    #   a number into a stock component:
     #
-    #   label.on_locale_changed = -> { label.text = due_date.strftime(fmt) }
+    #     label.on_locale_changed { label.text = due_date.strftime(fmt) }
     #
-    # @return [Proc, nil]
-    attr_accessor :on_locale_changed
+    #   @return [Listeners]
+    listener :on_locale_changed
 
     # Whether this component's tree is mounted on a UI, {ScreenPane} being the
     # root of every displayed tree.
@@ -555,7 +780,7 @@ module Tuile
     # A property of the parent chain alone — no {Screen} is consulted, so
     # assembling a tree needs no screen in the process at all:
     #
-    #   layout = Component::Layout::Absolute.new
+    #   layout = Component::Layout::Vertical.new
     #   layout.add(label)      # legal with no Screen; neither is attached yet
     #   screen.content = layout # now both are
     #
@@ -596,10 +821,13 @@ module Tuile
     end
 
     # Where the hardware terminal cursor should sit when this component is the
-    # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
-    # {Screen} positions the hardware cursor after each repaint cycle by
+    # cursor owner, **in this component's own coordinates** — the ones it paints
+    # in, so a caret is `Point.new(column, row)` with no position added.
+    # {Screen#cursor_position} converts it. Returns `nil` to hide the cursor.
+    #
+    # The {Screen} positions the hardware cursor after each repaint cycle by
     # consulting the {Screen#focused} component only.
-    # @return [Point, nil] absolute screen coordinates, or nil to hide.
+    # @return [Point, nil] in this component's coordinates, or nil to hide.
     def cursor_position = nil
 
     # One line naming the component, its {#id} and its rect, plus whatever
@@ -643,6 +871,8 @@ module Tuile
     # @param at [Integer, nil] index to insert at; appends when nil.
     # @raise [TypeError] if `child` is not a {Component}.
     # @raise [ArgumentError] if `child` already has a parent.
+    # @raise [Tuile::Error] if `child` is a {Component::Overlay} not being
+    #   adopted as one of {ScreenPane#popups}.
     # @return [void]
     #
     # Final: one of the three mutators that write {#children} and the parent
@@ -651,8 +881,18 @@ module Tuile
       raise TypeError, "expected Component, got #{child.inspect}" unless child.is_a? Component
       raise ArgumentError, "#{child} already has a parent #{child.parent}" unless child.parent.nil?
 
+      # An overlay's placement, `open?`, `visible=` and outside-click dismissal
+      # all come from the pane's popup list, so anywhere else it would be
+      # unplaceable and undismissable. Membership, not the pane's identity,
+      # which would let the `content` slot through; checked before the push, so
+      # a refusal leaves the tree untouched.
+      if child.is_a?(Component::Overlay) && !(is_a?(ScreenPane) && has_popup?(child))
+        raise Tuile::Error, "#{child.class} belongs on the popup stack — open it (#{child.class}#open) " \
+                            "rather than adding it to #{self.class}"
+      end
       at.nil? ? @children.push(child) : @children.insert(at, child)
       child.parent = self
+      invalidate_layout
     end
 
     # Drops `child` and notifies {#handle_child_removed}.
@@ -688,6 +928,7 @@ module Tuile
 
       @children.delete(child)
       child.parent = nil
+      invalidate_layout
     end
 
     # Called once this component's tree has been mounted on a {ScreenPane},
@@ -766,33 +1007,24 @@ module Tuile
     def fire_lifecycle(attached)
       kids = children.dup
       attached ? handle_attached : handle_detached
+      # A mark taken while detached had no screen to go to; hand it over now
+      # that there is one (the `attached?` re-check covers a hook that detached
+      # us again). Flutter's `RenderObject#attach` does the same.
+      screen.invalidate_layout(self) if attached && @layout_dirty && attached?
       kids.each { _1.fire_lifecycle(attached) if _1.attached? == attached }
     end
 
-    # Called whenever the component width changes. Does nothing by default.
-    # @return [void]
-    def handle_width_changed; end
-
-    # Called on the parent after a direct child's {#visible=} flipped, so a
-    # container that divides space can re-divide it:
-    #
-    #   def handle_child_visibility_changed(_child)
-    #     super
-    #     relayout
-    #   end
+    # Called once the parent has given this component a different rect, before
+    # anything repaints. Does nothing by default.
     #
-    # **A container with layout arithmetic owes this override**, or a hidden
-    # child keeps its slot and its gap — the hole the flag exists to close.
-    # {Component::Layout::Absolute} owes nothing: its `rect=` is app
-    # arithmetic, and an app wanting the space back reads `visible?` there.
-    #
-    # Fires on the flip only, before the subtree is invalidated, never for a
-    # grandchild. {#visible=} repairs focus itself, so an override has nothing
-    # to inherit — it still calls `super`, per the class doc. Reached through
-    # `__send__`, so it may declare any visibility (`D_hook_visibility`).
-    # @param _child [Component] the direct child whose flag changed.
+    # The *edge*: for a reaction to the change itself, one that needs the old
+    # rect or must not repeat — closing a menu, escalating a repaint. State
+    # that merely *follows* from the size — a wrap, a scroll clamp — is
+    # re-derived in {#relayout} instead, which runs after every rect change
+    # on either axis and after every other mark too.
+    # @param _old_rect [Rect] the rect it had.
     # @return [void]
-    def handle_child_visibility_changed(_child); end
+    def handle_rect_changed(_old_rect); end
 
     # Mirror of {#handle_focus}: the component just lost focus, to another component
     # or to nothing. The commit point a Tab-away still reaches — Tab is
@@ -802,7 +1034,7 @@ module Tuile
     #   class TrimmedField < Component::TextField
     #     protected def handle_blur
     #       super
-    #       self.text = text.strip
+    #       self.value = text.strip
     #       false
     #     end
     #   end
@@ -840,8 +1072,8 @@ module Tuile
     #
     # Runs on the UI thread with {Screen#theme} already updated, so mutating
     # content (`text=`, `lines=`, …) is safe. Do not assign {Screen#theme=}
-    # here. Subclasses overriding this must call `super` so an assigned
-    # {#on_theme_changed=} listener keeps firing.
+    # here. Subclasses overriding this must call `super` so any
+    # {#on_theme_changed} listener keeps firing.
     #
     # Plumbing an app overrides and never calls, hence protected — and
     # {Screen}, not being a {Component}, fans it out through `__send__`, so an
@@ -849,7 +1081,7 @@ module Tuile
     # @return [void]
     #   is whatever the app's lambda happened to return.
     def handle_theme_changed
-      @on_theme_changed&.call
+      on_theme_changed.fire(ThemeChangedEvent.new(source: self))
     end
 
     # Called on every attached component (pre-order, popups included) when
@@ -859,7 +1091,7 @@ module Tuile
     # change invalidates the whole tree.
     #
     # Runs on the UI thread with {Screen#locale} already updated. Subclasses
-    # overriding it must call `super` so an assigned {#on_locale_changed=}
+    # overriding it must call `super` so any {#on_locale_changed}
     # listener keeps firing.
     #
     # Plumbing an app overrides and never calls, hence protected — {Screen}
@@ -868,7 +1100,7 @@ module Tuile
     # @return [void]
     #   is whatever the app's lambda happened to return.
     def handle_locale_changed
-      @on_locale_changed&.call
+      on_locale_changed.fire(LocaleChangedEvent.new(source: self))
     end
 
     # The formatting conventions to render and parse by ({Screen#locale}), or
@@ -894,12 +1126,89 @@ module Tuile
       screen.invalidate(self)
     end
 
+    # Marks this container as owing a {#relayout}: its children's rects are out
+    # of date, and the next {#flush_layout} will bring them up to date.
+    #
+    #   def spacing=(cells)
+    #     @spacing = cells
+    #     invalidate_layout      # every input to the arithmetic ends here
+    #   end
+    #
+    # The framework marks after `rect=`, after the three tree mutators and
+    # after a child's {#visible=} flips; a container marks for every *other*
+    # input to its own arithmetic.
+    #
+    # **The mark never runs the pass** — not even detached, where there is no
+    # settle to defer to and {#flush_layout} has to be asked for. That is what
+    # lets a constructor `add_child` before its ivars are written, and a
+    # container mutate its own bookkeeping in whatever order reads best: no
+    # `relayout` ever observes a container mid-configuration.
+    #
+    # Unlike {#invalidate}, a detached mark is *remembered* rather than
+    # dropped: attaching hands it to the {Screen}, so a tree assembled with no
+    # screen lays out as soon as it is mounted.
+    #
+    # **A mark made during this container's own {#relayout}, before it places
+    # its first child, is dropped** — the pass that would answer it is the one
+    # running. So hide or add a child, or set your own `spacing`, *first*:
+    #
+    #   def relayout
+    #     @sidebar.visible = width >= 60   # before `super`: one pass
+    #     super
+    #   end
+    #
+    # Once a child is placed, the division may already be stale, so a later
+    # mark is kept and costs a second pass.
+    # @return [void]
+    def invalidate_layout
+      return if LayoutPass.before_first_placement?(self)
+
+      @layout_dirty = true
+      screen.invalidate_layout(self) if attached?
+    end
+
+    # Assigns every child's rect, and is the only place a container may.
+    #
+    #   private def relayout
+    #     half = width / 2                       # `local_rect`, so no rect.left:
+    #     @left.rect  = Rect.new(0, 0, half, height)
+    #     @right.rect = Rect.new(half, 0, width - half, height)
+    #   end
+    #
+    # **`relayout` : geometry :: {#repaint} : ink.** Invoked by the framework,
+    # never called directly; derives every rect from current state, so it is
+    # idempotent and safe to run twice. It assigns *every* child on every pass,
+    # including when {#rect} is empty — a `return if rect.empty?` guard strands
+    # children at stale coordinates that the next full repaint paints them at
+    # (`D_empty_ancestor`).
+    #
+    # **It is also where a component re-derives what depends on its own size**
+    # — a wrap, a padded row cache, a scroll offset clamped to the viewport —
+    # because {#rect=} marks the component itself, so this runs after every
+    # rect change, width *or* height. It runs after every other mark as well,
+    # so a costly derivation keys itself on the size it was built at —
+    # {Component::TextView}'s:
+    #
+    #   def relayout
+    #     rewrap unless @wrapped_at == wrap_width   # not on every append
+    #     update_scroll_top_row_if_auto_scroll      # a taller viewport moves the bottom
+    #     @scrollbar.rect = …
+    #   end
+    #
+    # There is no width-changed hook; {#handle_rect_changed} is the edge, for a
+    # reaction to the change itself.
+    #
+    # Reached through `__send__`, so an override may be protected or private
+    # (`D_hook_visibility`). A leaf inherits the empty body and costs nothing.
+    # @return [void]
+    def relayout; end
+
     # Whether direct children fully tile {#rect}. Used by the default
     # {#repaint} to decide whether the framework needs to wipe gaps.
     #
     # Approximated by area: sum of (non-empty) child areas vs the parent's
     # area. Cheap, and correct as long as siblings don't overlap each other
-    # — which Tuile already requires (no clipping in the tiled tree).
+    # — which Tuile already requires of a tiled layout.
     # Children with empty rects contribute zero, since they paint nothing.
     #
     # A **hidden** child contributes zero for the same reason, and that is what
@@ -916,18 +1225,20 @@ module Tuile
     # below it. A `nil` extent declares nothing, so the whole rect is blanked.
     # Called by the default {#repaint}; a self-painter that skips `super` calls
     # it directly.
+    # @param canvas [Canvas] the paint context, at this component's own background.
     # @return [void]
-    def clear_outside_extent
+    def clear_outside_extent(canvas)
       e = extent
-      return clear_background if e.nil? # nothing declared: all of it is fair game
+      return canvas.fill(local_rect) if e.nil? # nothing declared: all of it is fair game
 
-      right = Rect.new(rect.left + e.width, rect.top, rect.width - e.width, e.height)
-      below = Rect.new(rect.left, rect.top + e.height, rect.width, rect.height - e.height)
+      right = Rect.new(e.width, 0, rect.width - e.width, e.height)
+      below = Rect.new(0, e.height, rect.width, rect.height - e.height)
       # Not this widget's own surface: a one-row Select handed a 25-row rect
       # would otherwise flood the other 24 with its field well.
-      bg = ambient_bg_color
-      clear_background(right, bg) unless right.empty?
-      clear_background(below, bg) unless below.empty?
+      canvas.with(bg_color: bg.ambient) do |ambient|
+        ambient.fill(right) unless right.empty?
+        ambient.fill(below) unless below.empty?
+      end
     end
 
     # Blanks the {#extent} itself, for a *container* whose children don't cover
@@ -943,64 +1254,35 @@ module Tuile
     # extent itself, and blanking that first is the re-emit `D_progress_bar`
     # bought back. Override it to decline when you paint your own ink into a
     # face cell no child covers.
+    # @param canvas [Canvas] the paint context, at this component's own background.
     # @return [void]
-    def clear_inside_extent
-      clear_background(extent_rect, ambient_bg_color)
+    def clear_inside_extent(canvas)
+      canvas.with(bg_color: bg.ambient) { _1.fill(local_extent_rect) }
     end
 
-    # The background this component paints when the app has set no {#bg_color} —
-    # `nil` by default, meaning "I have no surface of my own; whatever is behind
-    # me shows through". A widget that paints an opaque surface overrides it, and
-    # inheritance stops there: that is what keeps a form's fields looking like
-    # fields inside a tinted panel. Declare it unconditionally — a widget owned
-    # by a bigger one is told so with {BG_INHERIT}, and must not try to work it
-    # out from where it sits in the tree.
-    #
-    #   # a field: its own well, brighter while focused
-    #   def default_bg_color = active? ? screen.theme.active_bg_color : screen.theme.input_bg_color
+    # This component's background — protected, because stating a widget's own
+    # well is the widget's business; an app tints through {#bg_color=}.
     #
-    # Return whatever {#bg_color} accepts — a {Color}, a {Theme::Ref} or a state
-    # Hash. Branching on {#active?} and handing back one {Color}, as above, is
-    # the cheap form and allocates nothing on the paint path.
+    #   bg.default_color = ComponentBackground::INPUT_WELL   # in a field's initialize
     #
-    # Read the theme here rather than in an ivar: this runs at paint time, so a
-    # {Screen#theme=} restyles the widget with no {#handle_theme_changed} hook.
-    # @return [Color, Theme::Ref, Hash, nil]
-    def default_bg_color = nil
-
-    # Final, and protected: it answers what the *framework* paints with, and an
-    # app never needs it — {#clear_background} / {#draw_text} / {#draw_char}
-    # apply it already. A component states its own opinion by overriding
-    # {#default_bg_color}, an app by setting {#bg_color}; neither takes this
-    # over. Protected rather than private because the chain below is an
-    # explicit-receiver call, which Ruby forbids for a private method.
-    # @return [Color, nil] the background actually painted, for the state this
-    #   component is in right now: its {#error_bg_color}, else its {#bg_color},
-    #   else its {#default_bg_color}, else the nearest ancestor answering one of
-    #   those, else `nil` (terminal default). Resolved at paint time — never
-    #   cached, so the subtree tracks an ancestor's {#bg_color=}, a
-    #   {Screen#theme=}, a focus change and a validation verdict on its next
-    #   repaint.
-    def effective_bg_color
-      own = resolve_bg_color(error_bg_color) || resolve_bg_color(@bg_color) || resolve_bg_color(default_bg_color)
-      return parent&.effective_bg_color if own.nil? || own == BG_INHERIT
-
-      own
-    end
+    # Final: {Screen#canvas_for} and every descendant's chain read it.
+    # @return [ComponentBackground]
+    attr_reader :bg
 
     # The background a component paints while it is in an *error* state —
     # `nil` by default, meaning "I am not signalling one". {HasValidation}
     # overrides it, so every field has it and nothing else does.
     #
-    # It sits **above** {#bg_color} in {#effective_bg_color} rather than under
-    # it, unlike {#default_bg_color}. That is deliberate: an app tinting a panel
+    # It sits **above** {#bg_color} in the chain rather than under it, unlike
+    # {ComponentBackground#default_color}. That is deliberate: an app tinting a panel
     # would otherwise switch the validation signal off on the fields inside it,
     # silently. An app that wants different error colors changes the
     # {Theme#error_bg_color} tokens.
     #
-    # Read the theme here rather than in an ivar, and hand back one {Color}
-    # rather than a state {Hash} — {#default_bg_color}'s reasons, and this runs
-    # one level earlier than that on the same paint path.
+    # A hook rather than a {ComponentBackground} setter because it follows the
+    # validation state, and a pulled answer cannot go stale. Read the theme
+    # here rather than in an ivar, and hand back one {Color}: this runs first
+    # on every paint.
     # @return [Color, Theme::Ref, Hash, nil]
     def error_bg_color = nil
 
@@ -1009,11 +1291,11 @@ module Tuile
     # self-painting container can drop the default's blanket clear without also
     # dropping this by accident ({Component::Window} is the case):
     #
-    #   def repaint
+    #   def repaint(canvas)
     #     return if rect.empty?
     #
     #     invalidate_children      # never optional
-    #     paint_my_own_chrome
+    #     paint_my_own_chrome(canvas)
     #   end
     #
     # @return [void]
@@ -1021,54 +1303,42 @@ module Tuile
       children.each { |c| screen.invalidate(c) }
     end
 
-    # Clears the background: fills every cell with a blank in the
-    # {#effective_bg_color} (the terminal default when none is inherited).
-    #
-    # A component that paints part of its {#rect} itself passes just the part it
-    # *doesn't* — blanking a cell it is about to overwrite anyway makes that cell
-    # dirty, and {Buffer#flush} then re-emits it even though nothing visibly
-    # changed.
-    # @param area [Rect] the region to blank; defaults to the whole {#rect}.
-    # @param bg [Color, nil] the color to blank with; defaults to
-    #   {#effective_bg_color}, i.e. this component's own surface.
-    # @return [void]
-    def clear_background(area = rect, bg = effective_bg_color)
-      screen.buffer.fill(area, bg ? StyledString::Style.new(bg:) : StyledString::Style::DEFAULT)
-    end
+    private
 
-    # {Buffer#set_text} wrapper that fills {#effective_bg_color} behind any span
-    # with no bg of its own (via {StyledString#under_bg}), so an inherited
-    # {#bg_color} — or an invalid field's error well — shows through the content
-    # a component paints. A no-op layer when none is inherited. Self-painters
-    # (those skipping the {#repaint} auto-clear) paint through this instead of
-    # {Screen#buffer} directly.
-    # @param x [Integer] starting column.
-    # @param y [Integer] row.
-    # @param styled [StyledString]
+    # Clears the mark and runs {#relayout} — the sole invocation site of
+    # `relayout`, reached only from {LayoutPass.drain}.
     # @return [void]
-    def draw_text(x, y, styled)
-      screen.buffer.set_text(x, y, styled.under_bg(effective_bg_color))
+    def perform_relayout
+      @layout_dirty = false
+      LayoutPass.run(self) { relayout }
     end
 
-    # {#draw_text}'s single-grapheme counterpart: writes `grapheme` at `(x, y)`,
-    # filling {#effective_bg_color} when `style` carries no background of its
-    # own.
-    # @param x [Integer] column.
-    # @param y [Integer] row.
-    # @param grapheme [String] one grapheme cluster.
-    # @param style [StyledString::Style]
-    # @return [void]
-    def draw_char(x, y, grapheme, style = StyledString::Style::DEFAULT)
-      bg = effective_bg_color
-      style = style.merge(bg:) if bg && style.bg.nil?
-      screen.buffer.set_char(x, y, grapheme, style)
+    # The nearest ancestor whose pending or running {#relayout} would rewrite
+    # this component's {#rect}, or `nil` when the rect is current —
+    # {#rect_stale?}'s answer, with the culprit kept for {StrictLayout}'s
+    # message.
+    #
+    # Two ways to owe it: a marked ancestor, and one whose pass is running and
+    # has not yet placed the child on the way down — a hook fired mid-pass, a
+    # focus repair from a child hidden there, reading a sibling. Strictly
+    # ancestors, never `self`: a container's own flag means its children are
+    # stale, and {#perform_relayout} clears the flag before the body runs, so a
+    # `relayout` reading its own `width` is asking a settled question.
+    # @return [Component, nil]
+    def stale_layout_ancestor
+      node = self
+      until node.parent.nil?
+        return node.parent if node.parent.layout_dirty? || LayoutPass.unplaced?(node)
+
+        node = node.parent
+      end
+      nil
     end
 
-    private
-
     # Hands focus out of the subtree just hidden, if it was in there, through
     # the parent's {#handle_child_removed} — see there for why hiding reuses the
-    # removal repair instead of growing a second one.
+    # removal repair instead of growing a second one. {List#interactive=}
+    # reuses it too, for a component that stays shown but stops taking focus.
     #
     # The parent is necessarily showing (focus was inside it a moment ago, and
     # {Screen#focused=} refuses a hidden target), so its assignment can't bounce.
@@ -1080,53 +1350,5 @@ module Tuile
       cursor = cursor.parent until cursor.nil? || cursor.equal?(self)
       parent.handle_child_removed(self) unless cursor.nil?
     end
-
-    # What surrounds this component — an app-set {#bg_color}, else whatever the
-    # parent paints where this component is not. Skips {#default_bg_color}, the
-    # one thing that colors this widget's *own* surface, which is what makes it
-    # the right answer for the dead tail outside {#extent}.
-    # @return [Color, nil]
-    def ambient_bg_color
-      own = resolve_bg_color(@bg_color)
-      return parent&.effective_bg_color if own.nil? || own == BG_INHERIT
-
-      own
-    end
-
-    # Collapses one level of the background chain to the {Color} it means right
-    # now: picks the entry for this component's current state out of a state
-    # Hash, and resolves a {Theme::Ref} against the live theme. An absent state
-    # key yields `nil`, so resolution falls through to the next level — which is
-    # what lets `bg_color = { active: … }` keep the widget's own normal well.
-    # @param value [Color, Theme::Ref, Hash, nil]
-    # @return [Color, nil]
-    def resolve_bg_color(value)
-      case value
-      when nil then nil
-      when Hash then resolve_bg_color(value[active? ? :active : :normal])
-      when Theme::Ref then value.resolve(screen.theme)
-      else value
-      end
-    end
-
-    # Validates and normalizes what {#bg_color=} was handed, so a bad token or a
-    # misspelled state raises at the assignment rather than deep in a repaint.
-    # @param value [Object]
-    # @return [Color, Theme::Ref, Hash, nil]
-    # @raise [ArgumentError] on a Hash key outside {BG_STATES}.
-    # @raise [KeyError] on a {Theme::Ref} naming an absent custom token.
-    def coerce_bg_color(value)
-      case value
-      when nil, Color, BG_INHERIT then value
-      when Theme::Ref then value.tap { _1.resolve(screen.theme) }
-      when Hash
-        unknown = value.keys - BG_STATES
-        raise ArgumentError, "unknown background state(s) #{unknown.join(", ")}; known: #{BG_STATES.join(", ")}" \
-          unless unknown.empty?
-
-        value.to_h { |state, color| [state, coerce_bg_color(color)] }.freeze
-      else Color.coerce(value)
-      end
-    end
   end
 end