tuile 0.16.0 → 0.17.0

data/lib/tuile/component/confirm_window.rb

@@ -20,7 +20,7 @@ module Tuile
     #   dialog.button("Save")    { save! }
     #   dialog.button("Discard") { discard! }
     #   dialog.button("Cancel")             # no action: pressing it dismisses
-    #   dialog.on_dismiss = -> { stay_put }
+    #   dialog.on_dismiss { stay_put }
     #   dialog.open
     #
     # **Every button closes the dialog.** A button with a block then fires it; a
@@ -80,7 +80,6 @@ module Tuile
         @popup = nil
         @chosen = false
         @message = nil
-        @on_dismiss = nil
         # Insertion-ordered; identity-keyed so equal captions stay two buttons.
         @actions = {}.compare_by_identity
         @mnemonics = {}
@@ -93,11 +92,18 @@ module Tuile
         self.content = @box
       end
 
-      # Callback taking no arguments, fired when the dialog is dismissed — ESC,
-      # `q`, an outside click, or a {#button} declared without a block. Fires
-      # exactly once per {#open}, and never when an action button was chosen.
-      # @return [Proc, nil]
-      attr_accessor :on_dismiss
+      # What {#on_dismiss} fires.
+      #
+      # @!attribute [r] source
+      #   @return [ConfirmWindow] the dialog that was dismissed.
+      DismissEvent = Data.define(:source) { include Tuile::Event }
+
+      # @!method on_dismiss
+      #   Fired with a {DismissEvent} when the dialog is dismissed — ESC, `q`, an
+      #   outside click, or a {#button} declared without a block. Fires exactly
+      #   once per {#open}, and never when an action button was chosen.
+      #   @return [Listeners]
+      listener :on_dismiss
 
       # @return [String, StyledString, Component, nil] whatever {#message=} was
       #   given — set a `String`, read that `String` back. The component
@@ -169,7 +175,7 @@ module Tuile
         # is the downcased matching key.
         cue = mnemonic == :auto ? styled.to_s.grapheme_clusters.first : mnemonic
         btn = Button.new(letter ? underline_mnemonic(styled, cue) : styled)
-        btn.on_click = -> { activate(btn) }
+        btn.on_click { activate(btn) }
         @actions[btn] = action
         @mnemonics[letter] = btn unless letter.nil?
         @button_row.add(btn, Layout::Fixed[btn.caption.display_width + 4])
@@ -191,7 +197,7 @@ module Tuile
         @popup&.content = nil
         @chosen = false
         @popup = MeasuredPopup.new(self)
-        @popup.on_close = -> { notice_dismissed }
+        @popup.on_close { notice_dismissed }
         @popup.open
       end
 
@@ -292,7 +298,7 @@ module Tuile
         window.message = message
         window.button(confirm, &action)
         window.button(cancel)
-        window.on_dismiss = on_dismiss
+        window.on_dismiss << on_dismiss if on_dismiss
         window.open
       end
 
@@ -307,23 +313,19 @@ module Tuile
         confirm(caption, message, confirm: "Yes", cancel: "No", on_dismiss:, &action)
       end
 
-      # The {Popup} that {#open} wraps the dialog in: its declared size is
-      # derived from the dialog on every {#reposition}, so a message change and
-      # a SIGWINCH both re-measure against the current screen.
+      # The {Popup} that {#open} wraps the dialog in: its size is measured from
+      # the dialog on every layout pass, so a message change and a SIGWINCH both
+      # re-measure against the current screen.
       class MeasuredPopup < Popup
         # @param window [ConfirmWindow]
         def initialize(window)
-          # Before super: Popup#initialize ends in the first #reposition call.
           @window = window
           super(content: window)
         end
 
-        # @return [void]
-        def reposition
-          # The ivar, not #declared_size= — the writer calls reposition itself.
-          @declared_size = @window.measured_size(screen.size)
-          super
-        end
+        # @param screen_size [Size]
+        # @return [Size] {ConfirmWindow#measured_size}.
+        def declared_size_in(screen_size) = @window.measured_size(screen_size)
       end
       private_constant :MeasuredPopup
 
@@ -339,7 +341,7 @@ module Tuile
         action = @actions[btn]
         @chosen = true
         @popup&.close
-        action.nil? ? @on_dismiss&.call : action.call
+        action.nil? ? fire_dismissed : action.call
       end
 
       # The popup's on_close: fires {#on_dismiss} unless a button was chosen —
@@ -350,9 +352,12 @@ module Tuile
         return if @chosen
 
         @chosen = true
-        @on_dismiss&.call
+        fire_dismissed
       end
 
+      # @return [void]
+      def fire_dismissed = on_dismiss.fire(DismissEvent.new(source: self))
+
       # @param delta [Integer] -1 or 1.
       # @return [Boolean] false when focus is not on a button (the key bubbles on).
       def focus_button_step(delta)

data/lib/tuile/component/date_field.rb

@@ -6,7 +6,7 @@ module Tuile
     # empty). Give it a single-row {#rect}:
     #
     #   field = Component::DateField.new
-    #   field.on_value_change = ->(d) { puts d.inspect }  # Date or nil, per commit
+    #   field.on_value_change { |e| puts e.value.inspect }  # Date or nil, per commit
     #   field.value = Date.new(2026, 9, 4)                # field shows "2026-09-04"
     #   field.placeholder                                 # => "yyyy-mm-dd"
     #   field.clear                                       # empties it; value => nil
@@ -110,8 +110,8 @@ module Tuile
         editor.max_text_length = MAX_TEXT_LENGTH
         # Claiming the editor's two arrow slots, not the general interceptor:
         # that one stays free for the app.
-        editor.on_key_up = -> { step(1) }
-        editor.on_key_down = -> { step(-1) }
+        editor.on_key_up { step(1) }
+        editor.on_key_down { step(-1) }
         @settled = false
         @placeholder_override = nil
         # Both nil: follow the screen's locale until an app overrides them.
@@ -144,13 +144,14 @@ module Tuile
       #   field.value = Time.now   # shows today; reads back a Date, time dropped
       #
       # @param new_value [Date, nil] `nil` empties the field.
+      # @param from_user [Boolean] see {HasValue#set_value}.
       # @return [void]
-      def value=(new_value)
-        editor.text = new_value.nil? ? "" : new_value.strftime(formats.first)
+      def set_value(new_value, from_user:)
+        editor.set_value(new_value.nil? ? "" : new_value.strftime(formats.first), from_user:)
         editor.caret = editor.text.length
         # The edit above announced nothing ({#notify_on_edit?}); a date written
         # rather than typed has no prefix to be mistaken for a value.
-        fire_if_changed
+        fire_if_changed(from_user:)
       end
 
       # `nil`, not `""`: a date field with no parseable date is empty.
@@ -189,7 +190,7 @@ module Tuile
       def formats=(list)
         @formats = list.nil? ? nil : Locale::DateFormats.validate(list)
         sync_placeholder
-        fire_if_changed
+        fire_if_changed(from_user: false)
       end
 
       # When the Gregorian calendar takes over from the Julian one, as a Julian
@@ -222,7 +223,7 @@ module Tuile
         end
 
         @calendar_start = start
-        fire_if_changed
+        fire_if_changed(from_user: false)
       end
 
       # Overrides the hint derived from the primary format.
@@ -248,6 +249,14 @@ module Tuile
       # @return [String, nil]
       def bad_input_message = value.nil? && !editor.text.empty? ? BAD_INPUT_MESSAGE : nil
 
+      # Every prefix of a date is bad input, so the report is latched to the
+      # commit gestures instead of shown per keystroke: `2`, `20`, `202` on the
+      # way to `2026-09-04` never redden and announce nothing, and a date the
+      # field cannot parse reddens the moment the user leaves the field or
+      # presses ENTER ({HasBadInput}).
+      # @return [Boolean]
+      def bad_input_settled? = @settled
+
       protected
 
       # Rewrites a buffer that parses in the primary format, leaving one that
@@ -256,7 +265,8 @@ module Tuile
       # @return [void]
       def commit
         date = value
-        self.value = date unless date.nil? # …which unsettles, hence the order
+        # The user's: a commit gesture, and a held notice announces here.
+        set_value(date, from_user: true) unless date.nil? # …which unsettles, hence the order
         settle(true)
       end
 
@@ -266,20 +276,14 @@ module Tuile
       # @return [Boolean]
       def notify_on_edit? = false
 
-      # Every prefix of a date is bad input, so the well is latched to the
-      # commit gestures instead of painted per keystroke: `2`, `20`, `202` on
-      # the way to `2026-09-04` never redden, and a date the field cannot parse
-      # reddens the moment the user leaves the field or presses ENTER
-      # ({HasBadInput}).
-      # @return [Boolean]
-      def bad_input_settled? = @settled
-
       # An edit is the user having another go, so the well goes quiet again
       # until the next commit gesture.
       # @return [void]
       def handle_editor_change
-        super
+        # Unsettled before the sync riding `super`, which would otherwise read
+        # the new buffer against the old latch.
         settle(false)
+        super
       end
 
       # Re-derives the hint (which was *pushed* into the editor, so a repaint
@@ -293,7 +297,7 @@ module Tuile
         sync_placeholder
         date = value
         self.value = date unless date.nil?
-        fire_if_changed # for the buffer that just *stopped* parsing: nothing above touched it
+        fire_if_changed(from_user: false) # for the buffer that just *stopped* parsing: nothing above touched it
       end
 
       private
@@ -307,6 +311,9 @@ module Tuile
         # Nothing else painted: an ENTER on an untouched buffer writes no cells,
         # and neither does leaving the field with bad input in it.
         invalidate
+        # The latch moves without the buffer, so this is the one input to the
+        # showable report that {HasBadInput}'s edit funnel cannot see.
+        sync_bad_input
       end
 
       # @param text [String]
@@ -330,7 +337,7 @@ module Tuile
       # @return [void]
       def step(delta)
         date = value
-        self.value = date.nil? ? Date.today : date + delta
+        set_value(date.nil? ? Date.today : date + delta, from_user: true)
       end
 
       # @return [void]

data/lib/tuile/component/date_time_field.rb

@@ -9,7 +9,7 @@ module Tuile
     #               ↑ the blank column is {Layout::Box#spacing}, not a component
     #
     #   f = Component::DateTimeField.new
-    #   f.on_value_change = ->(dt) { puts dt.inspect }   # DateTime or nil, per commit
+    #   f.on_value_change { |e| puts e.value.inspect }   # DateTime or nil, per commit
     #   f.value = DateTime.new(2026, 9, 14, 13, 45)      # "2026-09-14" / "13:45"
     #   f.clear                                          # empties both halves
     #
@@ -27,10 +27,10 @@ module Tuile
     #   f.date_field.calendar_start = Date::ITALY
     #   f.time_field.step = 900             # Up/Down walk a quarter hour
     #
-    # Two of their knobs are **claimed** by this field and must not be
-    # reassigned: each half's {HasValue#on_value_change} (that is how the
-    # composite hears them) and each half's {Component#bg_color} (see the well
-    # rule below).
+    # What this field owns on them: each half's {Component#bg_color} (the well
+    # rule below), and one listener on each half's {HasValue#on_value_change}
+    # and {HasBadInput#on_bad_input_change} — that is how the composite hears
+    # them, so append your own and never remove those.
     #
     # == The value is a `DateTime` at +00:00
     # Both halves feed it with no adapter, and the offset is a placeholder
@@ -56,8 +56,11 @@ module Tuile
     #   2026-09-14    (empty)     nil         "needs both a date and a time"   this field
     #
     # A half's bad input is the half's to paint, on its own latch, and this
-    # field paints nothing. Half-filled is nobody else's, so this field reddens
-    # whole — but **only while it is not active**: it judges you when you leave
+    # field paints nothing — but it does *report*: {HasBadInput#bad_input_message}
+    # relays the guilty half's message and {HasBadInput#on_bad_input_change}
+    # fires on that half's latch, so whoever has cells beside the pair prints the
+    # words the half has nowhere to put. Half-filled is nobody else's, so this
+    # field reddens whole — but **only while it is not active**: it judges you when you leave
     # and goes quiet when you come back to fix it. A validator's verdict
     # ({HasValidation#error_message=}) is by definition not attributable either,
     # and reddens whole with no latch at all.
@@ -70,10 +73,10 @@ module Tuile
     # == Implementation details
     # - **The halves keep their own wells, and this field's ink is *synced* onto
     #   them.** `error_bg_color` sits at the top of the background chain, so a
-    #   child answering {Component#default_bg_color} — every field does — never
+    #   child answering {ComponentBackground#default_color} — every field does — never
     #   inherits an ancestor's error level, so marking only this field would
     #   leave the halves untouched and reach no cell at all. So the halves are
-    #   marked {Component::BG_INHERIT} exactly while this field inks, and `nil`
+    #   marked {ComponentBackground::INHERIT} exactly while this field inks, and `nil`
     #   otherwise. A guilty half's *own* error well still beats the mark, which
     #   is what keeps the ink rule free of arithmetic.
     # - **The spacing column is nobody's surface** — {Component#clear_inside_extent}
@@ -129,7 +132,14 @@ module Tuile
         # one handed a three-row rect paints a three-row well.
         add(@date_field, Expand[DATE_WEIGHT], cross: Fixed[1])
         add(@time_field, Expand[TIME_WEIGHT], cross: Fixed[1])
-        [@date_field, @time_field].each { _1.on_value_change = ->(_) { handle_half_change } }
+        [@date_field, @time_field].each do |half|
+          half.on_value_change { |e| handle_half_change(from_user: e.from_user?) }
+          # A half's report moves without its value — garbage and an empty
+          # buffer both read `nil` — and this field relays it. The report
+          # only: that event carries no origin to announce a value with, and
+          # every change of a half's value reaches the slot above anyway.
+          half.on_bad_input_change { handle_half_report_change }
+        end
       end
 
       # @return [DateField] the left half; tune it, never replace it.
@@ -149,7 +159,13 @@ module Tuile
       end
 
       # Writes the date into one half and the time of day into the other, firing
-      # {HasValue#on_value_change} once if the value actually changed.
+      # {HasValue#on_value_change} once if the value actually changed. The
+      # halves are written programmatically whatever `from_user` says — their
+      # notices are muted — and this field's own event carries it.
+      #
+      # An app never needs this with `from_user: true` to reach a half: each
+      # half is a {DateField} / {TimeField} with its own {#set_value}, and a
+      # user's edit there already arrives here as the user's.
       #
       # @param new_value [DateTime, Time, nil] anything carrying both a civil
       #   date and a time of day; `nil` empties both halves.
@@ -157,7 +173,8 @@ module Tuile
       # @raise [TypeError] on a `Date` (it has no hour, and midnight would be
       #   invented) or anything else missing one of the two — checked before
       #   either half is written, so a rejected value leaves the field as it was.
-      def value=(new_value)
+      # @param from_user [Boolean] see {HasValue#set_value}.
+      def set_value(new_value, from_user:)
         unless new_value.nil? || CIVIL_PARTS.all? { new_value.respond_to?(_1) }
           raise TypeError,
                 "expected a date and time of day answering #{CIVIL_PARTS.join("/")}, got #{new_value.inspect}"
@@ -167,7 +184,8 @@ module Tuile
           date_field.value = new_value
           time_field.value = new_value
         end
-        fire_if_changed
+        sync_bad_input
+        fire_if_changed(from_user:)
       end
 
       # `nil`, not a pair of nils: a field with no parseable date *and* time is
@@ -182,19 +200,32 @@ module Tuile
         applying { [date_field, time_field].each(&:clear) }
         # Announced even though the halves hold their own notice: emptying is
         # not a half-typed prefix.
-        fire_if_changed
+        sync_bad_input
+        fire_if_changed(from_user: false)
       end
 
       # The guilty half's own report, the date's first when both are bad; else
       # the one fault no half can wear, a half-filled pair.
       # @return [String, nil]
       def bad_input_message
-        attributed = date_field.bad_input_message || time_field.bad_input_message
+        attributed = guilty_half&.bad_input_message
         return attributed unless attributed.nil?
 
         date_field.empty? ^ time_field.empty? ? HALF_FILLED_MESSAGE : nil
       end
 
+      # Relayed from the half whose message this field is carrying, so the report
+      # reaches a listener at the instant that half reddens rather than a focus
+      # edge later; the fault no half can wear settles on leaving this field.
+      #
+      # No latch ivar, deliberately: every input here is a fact something
+      # announces, which is what lets the sync sites be a complete list.
+      # @return [Boolean]
+      def bad_input_settled?
+        half = guilty_half
+        half ? half.bad_input_settled? : !active?
+      end
+
       # Sets the verdict and syncs the halves' wells onto it.
       # @param new_message [String, StyledString, nil]
       # @return [void]
@@ -210,7 +241,10 @@ module Tuile
       def active=(flag)
         was = active?
         super
-        sync_half_wells unless was == active?
+        return if was == active?
+
+        sync_half_wells
+        sync_bad_input
       end
 
       # @return [Size] the full width, one row — so a taller rect gets the
@@ -219,20 +253,19 @@ module Tuile
 
       protected
 
-      # The ink rule in the class doc, as an expression.
-      #
-      # No latch ivar, deliberately: every input here is a fact something
-      # announces, which is what lets the well sync have a complete call list. A
-      # half's `bad_input?` moves with every keystroke and announces nothing at
-      # all by design, so a latch of this field's own could not follow it.
+      # `false` while a half is guilty: that half paints the fault where it
+      # happened, and a well over the pair would say the other half was wrong
+      # too. This field reddens for the half-filled fault and for a verdict, the
+      # two nobody else can wear.
       # @return [Boolean]
-      def bad_input_settled? = !attributable? && !active?
+      def wears_bad_input_ink? = guilty_half.nil?
 
       private
 
-      # @return [Boolean] whether a half is holding input its own value cannot
-      #   represent, and so wears the error itself.
-      def attributable? = date_field.bad_input? || time_field.bad_input?
+      # @return [AbstractWrappingField, nil] the half holding input its own
+      #   value cannot represent, the date's first — it owns the message this
+      #   field relays, and the latch relayed with it.
+      def guilty_half = [date_field, time_field].find(&:bad_input?)
 
       # One idempotent sync over one condition, this field the sole writer of
       # its halves' {Component#bg_color} — the shape a hook-owned resource takes.
@@ -243,13 +276,23 @@ module Tuile
       # @return [void]
       def sync_half_wells
         ink = error_ink?
-        [date_field, time_field].each { _1.bg_color = ink ? BG_INHERIT : nil }
+        [date_field, time_field].each { _1.bg_color = ink ? ComponentBackground::INHERIT : nil }
+      end
+
+      # @param from_user [Boolean] what the half's write declared.
+      # @return [void]
+      def handle_half_change(from_user:)
+        sync_half_wells
+        return if @applying
+
+        sync_bad_input
+        fire_if_changed(from_user:)
       end
 
       # @return [void]
-      def handle_half_change
+      def handle_half_report_change
         sync_half_wells
-        fire_if_changed unless @applying
+        sync_bad_input unless @applying
       end
 
       # Runs `block` with the halves' notices suppressed, so a value written
@@ -262,13 +305,14 @@ module Tuile
         @applying = false
       end
 
+      # @param from_user [Boolean]
       # @return [void]
-      def fire_if_changed
+      def fire_if_changed(from_user:)
         v = value
         return if v == @last_value
 
         @last_value = v
-        on_value_change&.call(v)
+        on_value_change.fire(HasValue::ValueChangeEvent.new(source: self, value: v, from_user:))
       end
     end
   end

data/lib/tuile/component/fill.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # Fills every cell of its {#rect} with one glyph. Give it a one-column rect
+    # and `│` for a vertical rule between two borderless panes, a one-row rect
+    # and `─` for a horizontal one — the glyph decides the direction, the parent
+    # decides the length:
+    #
+    #   rule = Component::Fill.new("│", color: Theme.ref(:pane_frame))
+    #   bottom = Component::Layout::Horizontal.new
+    #   bottom.add(system_pane, Layout::Percent[40])
+    #   bottom.add(rule, Layout::Fixed[1])
+    #   bottom.add(log_pane, Layout::Expand[1])
+    #
+    # Display-only — not focusable, no keys, no mouse. The background behind
+    # the glyph is its own {Component#bg_color}, else inherited, as for any
+    # component.
+    class Fill < Component
+      # @param char [String] initial {#char=}.
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      #   initial {#color=}.
+      # @raise [ArgumentError, TypeError] see {#char=} and {#color=}.
+      def initialize(char, color: nil)
+        super()
+        @char = StyledString.validate_glyph(char, :char)
+        @color = nil
+        self.color = color
+      end
+
+      # @return [String] the glyph painted into every cell; one grapheme
+      #   cluster, one column wide.
+      attr_reader :char
+
+      # @return [Color, Theme::Ref, nil] the value as set, so a {Theme::Ref}
+      #   comes back unresolved; `nil` (the default) is the terminal's default
+      #   foreground.
+      attr_reader :color
+
+      # @param char [String]
+      # @return [void]
+      # @raise [TypeError] when `char` is not a String.
+      # @raise [ArgumentError] when `char` is not exactly one grapheme cluster
+      #   one column wide.
+      def char=(char)
+        char = StyledString.validate_glyph(char, :char)
+        return if @char == char
+
+        @char = char
+        invalidate
+      end
+
+      # Sets the glyph's color, live-resolved at paint time when given a
+      # {Theme::Ref} (so it follows a {Screen#theme=} with no
+      # {Component#handle_theme_changed} hook).
+      #
+      #   rule.color = :bright_black
+      #   rule.color = Theme.ref(:pane_frame)   # an app #custom token
+      #
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      #   coerced via {Color.coerce} unless it is a {Theme::Ref}; `nil` is the
+      #   terminal default.
+      # @return [void]
+      # @raise [KeyError] when a {Theme::Ref} names a token the current theme
+      #   lacks.
+      def color=(color)
+        color = Color.coerce(color) unless color.is_a?(Theme::Ref)
+        return if @color == color
+
+        color.resolve(screen.theme) if color.is_a?(Theme::Ref) # fail fast on a bad token
+
+        @color = color
+        invalidate
+      end
+
+      # Paints {#char} into every cell. Not `super`: the default's clear would
+      # dirty every cell just before it is painted over.
+      # @param canvas [Canvas] see {Component#repaint}.
+      # @return [void]
+      def repaint(canvas)
+        return if rect.empty?
+
+        row = StyledString.styled(@char * rect.width, fg: resolved_color)
+        rect.height.times { canvas.set_text(0, _1, row) }
+      end
+
+      private
+
+      # @return [Color, nil]
+      def resolved_color = @color.is_a?(Theme::Ref) ? @color.resolve(screen.theme) : @color
+    end
+  end
+end

data/lib/tuile/component/float_field.rb

@@ -6,7 +6,7 @@ module Tuile
     # the {IntegerField} twin, one Ruby type over. Give it a single-row {#rect}:
     #
     #   field = Component::FloatField.new
-    #   field.on_value_change = ->(x) { puts x.inspect }  # Float or nil, per change
+    #   field.on_value_change { |e| puts e.value.inspect }  # Float or nil, per change
     #   field.value = 19.99                               # field shows "19.99"
     #   field.clear                                       # empties it; value => nil
     #
@@ -79,8 +79,8 @@ module Tuile
       def initialize
         super(Field.new)
         # Not the general on_key interceptor: that slot stays free for the app.
-        editor.on_key_up = -> { step(1.0) }
-        editor.on_key_down = -> { step(-1.0) }
+        editor.on_key_up { step(1.0) }
+        editor.on_key_down { step(-1.0) }
       end
 
       # @return [Float, nil] the parsed buffer; `nil` when empty or not a
@@ -96,9 +96,10 @@ module Tuile
       #   is coerced with `Float()`, so an `Integer` `3` shows as `"3.0"`.
       # @raise [ArgumentError] on a non-numeric `String`, a NaN or an infinity.
       # @raise [TypeError] on a value `Float()` won't take at all (an `Array`).
+      # @param from_user [Boolean] see {HasValue#set_value}.
       # @return [void]
-      def value=(new_value)
-        editor.text = new_value.nil? ? "" : coerce(new_value).to_s
+      def set_value(new_value, from_user:)
+        editor.set_value(new_value.nil? ? "" : coerce(new_value).to_s, from_user:)
         editor.caret = editor.text.length
       end
 
@@ -130,7 +131,7 @@ module Tuile
       # `0.0`.
       # @param delta [Float]
       # @return [void]
-      def step(delta) = (self.value = (value || 0.0) + delta)
+      def step(delta) = set_value((value || 0.0) + delta, from_user: true)
     end
   end
 end