tuile 0.9.0 → 0.10.0

data/lib/tuile/component.rb

@@ -13,6 +13,8 @@ module Tuile
       @rect = Rect.new(0, 0, 0, 0)
       @active = false
       @on_theme_changed = nil
+      @bg_color = nil
+      @children = []
     end
 
     # @return [Rect] the rectangle the component occupies on screen.
@@ -47,30 +49,59 @@ module Tuile
       screen.focused = self
     end
 
-    # Repaints the component.
+    # @return [Color, Theme::Ref, nil] this component's own background — the
+    #   value as set, so a {Theme::Ref} comes back unresolved; `nil` when unset,
+    #   in which case it inherits from the parent (see {#effective_bg_color}),
+    #   ultimately the terminal default. {#effective_bg_color} is the resolved
+    #   {Color} to paint.
+    attr_reader :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.
     #
-    # The default does the bookkeeping that almost every component would
-    # otherwise have to remember: it clears the background and re-invalidates
-    # any direct children whose rects leave gaps in {#rect}. Concretely:
+    # A {Theme::Ref} is re-resolved against the theme each paint, so it tracks
+    # light/dark flips with no {#on_theme_changed} hook; a {Color} is fixed:
     #
-    # - Leaf (no children): always clears, so subclasses can paint their
-    #   content directly without an explicit `clear_background` call.
-    # - Container with children that fully tile {#rect}: skipped — the
-    #   children themselves will repaint and cover everything.
-    # - Container with gappy children (e.g. a form layout where widgets
-    #   don't tile): clears, then invalidates the children so they re-paint
-    #   on top of the cleared background. This is what makes mixed
-    #   field/button forms safe without each container learning a custom
-    #   damage-tracking pass.
+    #   panel.bg_color = Theme.ref(:panel_bg)   # theme-tracked
+    #   panel.bg_color = Color::GREY27          # fixed
     #
-    # Subclasses that paint their entire rect themselves (e.g. {Window}'s
-    # border draws over the area the default would clear; {Component::List}
-    # explicitly paints every row) may skip super and take full
-    # responsibility for {#rect}. Everything else should call super.
-    #
-    # A component must not draw outside of {#rect}.
+    # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil] a
+    #   {Theme::Ref}, else a color coerced via {Color.coerce}; `nil` unsets
+    #   (inherit from the parent).
+    # @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 = Color.coerce(color) unless color.is_a?(Theme::Ref)
+      return if @bg_color == color
+
+      color.resolve(screen.theme) if color.is_a?(Theme::Ref) # fail fast on a bad token
+      @bg_color = color
+      on_tree { |c| screen.invalidate(c) } if attached?
+    end
+
+    # @return [Color, nil] the background actually painted: this component's own
+    #   {#bg_color} if set (a {Theme::Ref} resolved against the current theme),
+    #   else the nearest ancestor's, else `nil` (terminal default). Resolved at
+    #   paint time — never cached, so the subtree tracks both an ancestor's
+    #   {#bg_color=} and a {Screen#theme=} on its next repaint.
+    def effective_bg_color
+      own = @bg_color
+      own = own.resolve(screen.theme) if own.is_a?(Theme::Ref)
+      own || parent&.effective_bg_color
+    end
+
+    # Repaints the component. The default does the bookkeeping most components
+    # need: it clears the background, and for a container whose children leave
+    # gaps in {#rect} it re-invalidates those children so they repaint over the
+    # cleared area (what makes mixed-width form layouts safe). A container whose
+    # children fully tile {#rect} is left alone — the children cover everything.
     #
-    # Only called when the component is attached.
+    # Call `super` from your own `repaint` to inherit this. Skip it only if you
+    # paint the whole {#rect} yourself ({Window}'s border, {Component::List}'s
+    # row-by-row paint). Never draw outside {#rect}. Only called when attached.
     # @return [void]
     def repaint
       return if rect.empty?
@@ -80,41 +111,17 @@ module Tuile
       children.each { |c| screen.invalidate(c) }
     end
 
-    # Called when a character is pressed on the keyboard. The default does
-    # nothing and reports the key as unhandled; input components
-    # ({Component::TextField}, {Component::List}, {Component::Button}, …)
-    # override it to act on keys they care about.
-    #
-    # Dispatch is owned by {ScreenPane#handle_key}: a {#key_shortcut} match
-    # anywhere in the active scope is captured first (suppressed while a
-    # cursor-owner is mid-edit), then the key is delivered to {Screen#focused}
-    # and bubbles up its ancestor chain until some component handles it. A
-    # component therefore only ever receives keys when it is on the focus chain
-    # — or when app code hands it a key directly — so it acts on the key alone
-    # and must never gate on its own {#active?} state.
+    # Called when a key is pressed; override to act on keys you care about (the
+    # default reports every key unhandled). A component only receives keys while
+    # it's on the focus chain — or when app code hands it one directly — so act
+    # on the key alone and never gate on your own {#active?} state. See book ch5
+    # for how a keystroke is routed to reach here.
     # @param _key [String] a key.
     # @return [Boolean] true if the key was handled, false if not.
     def handle_key(_key)
       false
     end
 
-    # A global keyboard shortcut. When pressed, will focus this component.
-    # @return [String, nil] shortcut, `nil` by default.
-    attr_accessor :key_shortcut
-
-    # @param key [String] keyboard key to look up.
-    # @return [Component, nil] the component whose {#key_shortcut} matches `key`,
-    #   or nil.
-    def find_shortcut_component(key)
-      return self if key_shortcut == key
-
-      children.each do |child|
-        sc = child.find_shortcut_component(key)
-        return sc unless sc.nil?
-      end
-      nil
-    end
-
     # Handles mouse event. Default implementation focuses this component when
     # clicked (if {#focusable?}).
     # @param event [MouseEvent]
@@ -140,16 +147,11 @@ module Tuile
 
     # Whether this component is a valid focus target. `false` by default —
     # passive components like {Label} are decoration and don't accept focus.
-    # The flag gates click-to-focus ({#handle_mouse}) and the focus-cascade
-    # in container components ({HasContent#on_focus}, {Layout#on_focus}).
-    # Independent from {#active?}: every component carries the active flag, but
-    # only focusable ones can become a focus target that puts themselves and
-    # their ancestors on the active chain.
-    #
-    # See also {#tab_stop?}: focusable controls _can_ receive focus (via click
-    # or programmatic assignment), but only tab stops participate in Tab /
-    # Shift+Tab cycling. Containers like {Window} and {Popup} are focusable
-    # (so a click on chrome lands focus) but are not tab stops.
+    # The flag gates click-to-focus and the container focus-cascade. Independent
+    # from {#active?}: every component carries the active flag, but only
+    # focusable ones can become a focus target that puts themselves and their
+    # ancestors on the active chain. Focusable is broader than {#tab_stop?} —
+    # a {Window} is focusable (a click on chrome lands focus) but not a tab stop.
     # @return [Boolean] true if this component can be focused.
     def focusable? = false
 
@@ -172,10 +174,16 @@ module Tuile
     # @return [Component] the root component of this component hierarchy.
     def root = parent.nil? ? self : parent.root
 
-    # List of child components, defaults to an empty array.
-    # @return [Array<Component>] child components. Must not be mutated! May be
-    #   empty.
-    def children = []
+    # Child components in paint order (siblings left to right, earlier ones
+    # painted under later ones), maintained by {#add_child} / {#remove_child}.
+    #
+    # Not meant to be overridden: a container that computed this from its own
+    # slots could disagree with the parent pointers, and {#attached?} walks the
+    # chain while subtree walks use this list. Named slots are readers *over*
+    # the array (`Window#footer`), never a second copy of it.
+    # @return [Array<Component>] child components. Must not be mutated by
+    #   callers! May be empty.
+    attr_reader :children
 
     # Calls block for this component and for every descendant component.
     # @yield [component]
@@ -201,31 +209,33 @@ module Tuile
     attr_writer :on_theme_changed
 
     # Called on every attached component (pre-order, popups included) when
-    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=}
-    # assignment and on OS appearance flips.
+    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=} and on
+    # OS appearance flips. The hook exists for app *content* whose colors were
+    # baked in from the old theme (a {Label#text} / {List#lines} {StyledString}
+    # styled with `theme[:accent]`); rebuild it here by re-running the code that
+    # rendered it. See book ch6 for why built-in accents need no such handling.
     #
-    # Built-in components read {Screen#theme} at paint time, so their accents
-    # restyle automatically; this hook exists for *content* whose colors the
-    # app baked in from the old theme — a {Label#text} / {List#lines} /
-    # {TextView#text} {StyledString} styled with `theme[:accent]` and the
-    # like. Only the app knows which of its colors were theme-derived (as
-    # opposed to inherent to the data, e.g. log-level colors), so it rebuilds
-    # them here, re-running the same code that rendered them initially.
-    #
-    # Runs on the UI thread; {Screen#theme} already returns the new theme.
-    # Mutating content (`text=`, `lines=`, …) is safe — repaint coalesces per
-    # event-loop tick. Do not assign {Screen#theme=} from inside the hook.
-    #
-    # Subclasses overriding this should call `super` so an assigned
+    # 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.
     # @return [void]
     def on_theme_changed
       @on_theme_changed&.call
     end
 
-    # @return [Boolean] true if this component's tree is currently mounted on
-    #   the {Screen}, i.e. its root is the {ScreenPane}.
-    def attached? = root == screen.pane
+    # Whether this component's tree is mounted on a UI, {ScreenPane} being the
+    # root of every displayed tree.
+    #
+    # 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.add(label)      # legal with no Screen; neither is attached yet
+    #   screen.content = layout # now both are
+    #
+    # @return [Boolean] true if {#root} is a {ScreenPane}.
+    def attached? = root.is_a?(ScreenPane)
 
     # Called by container components after `child` has been detached from
     # `self.children` (its `parent` is already nil and it is no longer in the
@@ -265,8 +275,128 @@ module Tuile
 
     protected
 
-    # @return [Component, nil]
-    attr_writer :parent
+    # Adopts `child`: places it in {#children} and wires its parent pointer.
+    #
+    #   add_child(@status_bar)                              # paints last
+    #   add_child(popup, at: @children.index(@status_bar))  # …just before it
+    #
+    # @param child [Component] must not already have a parent.
+    # @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.
+    # @return [void]
+    def add_child(child, at: nil)
+      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?
+
+      at.nil? ? @children.push(child) : @children.insert(at, child)
+      child.parent = self
+    end
+
+    # Drops `child` and notifies {#on_child_removed}.
+    # @param child [Component]
+    # @raise [ArgumentError] if `child` is not a child of this component.
+    # @return [void]
+    def remove_child(child)
+      detach_child(child)
+      on_child_removed(child)
+    end
+
+    # Drops `child` *without* notifying — for a container swapping a named slot,
+    # which owes the {#on_child_removed} call once the new occupant is wired:
+    #
+    #   detach_child(old)
+    #   @content = new
+    #   add_child(new, at: 0)
+    #   on_child_removed(old)   # focus repair cascades into the *new* content
+    #
+    # The child leaves {#children} before its pointer is cleared, so nothing
+    # observes a child whose parent has disowned it while still listing it.
+    # @param child [Component]
+    # @raise [ArgumentError] if `child` is not a child of this component.
+    # @return [void]
+    def detach_child(child)
+      raise ArgumentError, "#{child} is not a child of #{self}" unless @children.include?(child)
+
+      @children.delete(child)
+      child.parent = nil
+    end
+
+    # Called once this component's tree has been mounted on a {ScreenPane},
+    # i.e. when {#attached?} flips to true — the place to acquire whatever is
+    # supposed to live for exactly as long as the component is on screen:
+    #
+    #   def on_attached
+    #     @ticker = screen.event_queue.tick_fps(10) { advance }
+    #   end
+    #
+    #   def on_detached
+    #     @ticker&.cancel
+    #     @ticker = nil
+    #   end
+    #
+    # `on_attached` starts what `on_detached` stops; both must be cheap and
+    # idempotent, since a component moved between parents is genuinely detached
+    # in between and gets both, in that order. Whatever you acquire here you
+    # must release in {#on_detached} — nothing else will. Not a destructor:
+    # process teardown does *not* fire {#on_detached}.
+    #
+    # {#invalidate} needs no guard: {#attached?} is already true here (and
+    # already false in {#on_detached}, where it no-ops). Do not read {#rect} —
+    # a parent assigns it *after* wiring, so it is still stale. Runs on the
+    # thread that owns the UI.
+    # @return [void]
+    def on_attached; end
+
+    # Mirror of {#on_attached}, called once the tree has been unmounted — see
+    # there for the contract. Two things are still mid-flight when it runs, both
+    # deliberate: {Screen#focused} may still point into this subtree (repair
+    # happens after), and the ex-parent's own bookkeeping may not be finished.
+    # So release resources here and don't inspect the tree around you.
+    # @return [void]
+    def on_detached; end
+
+    # Rewires the parent pointer and, when that changes whether the component is
+    # {#attached?}, fires {#on_attached} / {#on_detached} across the whole
+    # subtree. The sole firing site: `add_child` / `detach_child` are the only
+    # callers, and they update {#children} *before* calling this, so a hook sees
+    # a tree whose list and pointers already agree.
+    #
+    # Reparenting inside an already-attached tree fires nothing (attachedness
+    # doesn't change), and neither does building a detached tree.
+    # @param new_parent [Component, nil]
+    # @return [void]
+    def parent=(new_parent)
+      was_attached = attached?
+      @parent = new_parent
+      return if was_attached == attached?
+
+      fire_lifecycle(attached?)
+    end
+
+    # Walks self-then-children calling one lifecycle hook, delivering at most one
+    # call per component per transition however the hooks mutate the tree. Two
+    # guards, because a hook runs *before* its own children are visited:
+    #
+    # - the **snapshot** covers a child a hook *adds* — it isn't in `kids`, and
+    #   fires exactly once through its own `parent=`;
+    # - the **state re-check** covers a child a hook *removes*. Matching on
+    #   current attachedness rather than on `parent.equal?(self)`: a child pulled
+    #   out during a detach walk is *already* detached, so its own `parent=` saw
+    #   no transition and stayed silent — a parentage check would skip it too and
+    #   it would never hear `on_detached` at all. The reverse case (pulled out
+    #   during an *attach* walk) gets `on_detached` from its own `parent=` and no
+    #   `on_attached`, which is why the hooks are required to be idempotent: an
+    #   unpaired detach releases nothing, whereas firing `on_attached` at a
+    #   component that is no longer attached would start a ticker nothing stops.
+    #
+    # @param attached [Boolean] true to fire {#on_attached}, false for {#on_detached}.
+    # @return [void]
+    def fire_lifecycle(attached)
+      kids = children.dup
+      attached ? on_attached : on_detached
+      kids.each { _1.fire_lifecycle(attached) if _1.attached? == attached }
+    end
 
     # Called whenever the component width changes. Does nothing by default.
     # @return [void]
@@ -300,11 +430,44 @@ module Tuile
       total >= rect.width * rect.height
     end
 
-    # Clears the background: prints spaces into all characters occupied by the
-    # component's rect.
+    # 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}.
+    # @return [void]
+    def clear_background(area = rect)
+      bg = effective_bg_color
+      screen.buffer.fill(area, bg ? StyledString::Style.new(bg:) : StyledString::Style::DEFAULT)
+    end
+
+    # {Buffer#set_line} wrapper that fills {#effective_bg_color} behind any span
+    # with no bg of its own (via {StyledString#under_bg}), so an inherited
+    # {#bg_color} shows through the content a component paints. A no-op layer
+    # when nothing 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]
+    # @return [void]
+    def draw_line(x, y, styled)
+      screen.buffer.set_line(x, y, styled.under_bg(effective_bg_color))
+    end
+
+    # {#draw_line}'s single-grapheme counterpart: writes `grapheme` at `(x, y)`,
+    # filling {#effective_bg_color} when `style` carries no bg of its own.
+    # @param x [Integer] column.
+    # @param y [Integer] row.
+    # @param grapheme [String] one grapheme cluster.
+    # @param style [StyledString::Style]
     # @return [void]
-    def clear_background
-      screen.buffer.fill(rect)
+    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)
     end
   end
 end

data/lib/tuile/event_queue.rb

@@ -48,24 +48,18 @@ module Tuile
     end
 
     # Schedules `block` to fire on the event-loop thread every `seconds`,
-    # passing a 0-based monotonically increasing tick counter. The interval is
-    # in **seconds** — the conventional scheduling unit (`sleep`,
-    # `Concurrent::TimerTask#execution_interval`, …) — so `tick(0.2)` fires five
-    # times a second. Use it for periodic UI refresh from a background task
-    # (poll a status, redraw a clock). For animation, where frames-per-second
-    # is the natural unit, {#tick_fps} reads better.
-    #
-    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
-    # stop it.
+    # passing a 0-based monotonically increasing tick counter — `tick(0.2)`
+    # fires five times a second. Use it for periodic UI refresh (poll a status,
+    # redraw a clock); for animation, {#tick_fps} reads more naturally. The
+    # returned {Ticker} controls the schedule — {Ticker#cancel} stops it.
     #
     # **Errors:** if `block` raises, the {Ticker} cancels itself and the
-    # exception flows through the normal event-loop error path — i.e.
-    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
-    # broken block from spamming `on_error` at the tick rate.
+    # exception flows through the normal event-loop error path
+    # ({Screen#on_error} by default) — auto-cancel keeps a broken block from
+    # spamming `on_error` at the tick rate.
     #
-    # Tickers reuse `concurrent-ruby`'s shared timer thread
-    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
-    # threads, just more work on the shared scheduler.
+    # Tickers reuse `concurrent-ruby`'s shared timer thread, so adding more
+    # tickers doesn't add threads.
     #
     # @param seconds [Numeric] interval between firings, must be positive.
     #   Fractional values are fine (`tick(0.05)` ⇒ ~20 firings a second).
@@ -149,8 +143,11 @@ module Tuile
       end
     end
 
-    # @return [Boolean] true if this thread is running inside an event queue.
-    def locked? = @run_lock.owned?
+    # @return [Boolean] true if a {#run_loop} is in progress on *any* thread.
+    def running? = @run_lock.locked?
+
+    # @return [Boolean] true if this thread is the one running {#run_loop}.
+    def on_loop_thread? = @run_lock.owned?
 
     # Stops ongoing {#run_loop}. The stop may not be immediate: {#run_loop} may
     # process a bunch of events before terminating.

data/lib/tuile/fake_event_queue.rb

@@ -8,8 +8,17 @@ module Tuile
       @tickers = []
     end
 
-    # @return [Boolean]
-    def locked? = true
+    # Lets a spec assert that a component started a ticker, and — via
+    # {FakeTicker#cancelled?} — that it cancelled one rather than merely
+    # dropping it. Cancelled tickers stay here until the next {#tick_once}
+    # prunes them.
+    # @return [Array<FakeTicker>] the registered tickers, in creation order.
+    attr_reader :tickers
+
+    # @return [Boolean] always false — {#run_loop} raises, so no loop ever runs.
+    def running? = false
+    # @return [Boolean] always true.
+    def on_loop_thread? = true
     # @return [void]
     def stop; end
 

data/lib/tuile/fake_screen.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 module Tuile
-  # Testing only — a screen which doesn't paint anything and pretends that the
-  # lock is held. This way, the TTY running the tests is not painted over.
+  # Testing only — a screen which doesn't paint anything, so the TTY running
+  # the tests is not painted over. It runs no event loop, so
+  # {Screen#check_locked} admits the thread that called {Screen.fake}: a spec
+  # mutating the UI from a *spawned* thread raises, exactly as an app would.
   #
   # Intended for unit-testing individual components: instantiate a component,
   # mutate it, and assert against {#prints} or {#invalidated?}. It does not
@@ -35,9 +37,6 @@ module Tuile
     #   on `prints` for cursor and housekeeping escapes.
     attr_reader :prints
 
-    # @return [void]
-    def check_locked; end
-
     # @return [void]
     def clear
       @prints.clear

data/lib/tuile/fraction.rb

@@ -2,16 +2,12 @@
 
 module Tuile
   # A width/height ratio, each a float in `0.0..1.0` — the single relational
-  # sizing primitive in Tuile. It exists for exactly one job: sizing a
-  # {Component::Popup} against the screen. A popup has no siblings competing for
-  # space and no rectangle in a tiled layout, so "half the screen, centered" is
-  # the sensible default, and that wants a ratio rather than a hard-coded cell
-  # count that would be wrong on the next terminal size.
-  #
-  # Tiled components are *not* sized this way: their parent computes explicit
-  # integer rects in its own `rect=` and hands them down. `Fraction` is
-  # deliberately scoped to {Component::Popup#size=} and is not a general layout
-  # primitive.
+  # sizing primitive in Tuile, scoped to one job: sizing a {Component::Popup}
+  # against the screen (a popup has no siblings competing for space, so "half
+  # the screen, centered" beats a hard-coded cell count that breaks on the next
+  # terminal size). It is deliberately *not* a general layout primitive — tiled
+  # components get explicit integer rects computed by their parent's `rect=`.
+  # See book ch3 for the layout model.
   #
   # Resolve it against a reference {Size} (the screen) to get concrete integer
   # cells: