tuile 0.15.0 → 0.16.0

data/lib/tuile/component/abstract_wrapping_field.rb

@@ -61,6 +61,12 @@ module Tuile
     # default button still sees it; only an {#on_enter} of this field's own
     # consumes it, which is {TextField#on_enter}'s existing contract.
     #
+    # == When the value notice fires
+    # Per edit by default. A field whose grammar is not prefix-closed sets
+    # {#notify_on_edit?} to `false` and lets the notice settle onto those same
+    # two gestures, so a form is never handed a half-typed date that happens to
+    # parse ({DateField}, {TimeField}).
+    #
     # == Implementation details
     # - **{HasValue#value} and {#value=} raise until overridden.** The inherited
     #   pair stores into `@value` and never touches the editor, so a subclass
@@ -71,7 +77,7 @@ module Tuile
     # - **The editor's `on_change` and `on_enter` slots are claimed** — for that
     #   guard, and to commit before an app's ENTER handler runs. A slot cannot
     #   be shared, so a subclass reacting to buffer edits overrides
-    #   {#on_editor_change} (every edit), {#value=} or {#commit} rather than
+    #   {#handle_editor_change} (every edit), {#value=} or {#commit} rather than
     #   reassigning either.
     # - **Not for a field whose editor is a *filter*.** This base assumes the
     #   buffer is a rendering of the value, so an edit may change the value.
@@ -97,8 +103,8 @@ module Tuile
         # field's bg_color reaches the cells the editor paints.
         editor.bg_color = BG_INHERIT
         editor.on_change = lambda do |_text|
-          on_editor_change
-          fire_if_changed
+          handle_editor_change
+          fire_if_changed if notify_on_edit?
         end
         add_child(editor, at: 0)
       end
@@ -119,7 +125,13 @@ module Tuile
       # already reads {HasValue#empty_value}, so clearing through {#value=} could
       # leave the glyphs on screen ({HasBadInput}).
       # @return [void]
-      def clear = editor.clear
+      def clear
+        editor.clear
+        # Announced here rather than through the editor's change, so a field
+        # holding its notice ({#notify_on_edit?}) still reports an emptying as
+        # it happens: emptying is not a half-typed prefix.
+        fire_if_changed
+      end
 
       # @return [String, nil] the hint the editor paints while empty
       #   ({HasPlaceholder}).
@@ -142,9 +154,9 @@ module Tuile
         @on_enter = callback
         # Wrapped rather than forwarded, so an app's ENTER handler reads a
         # committed buffer. A nil callback leaves the editor's own slot nil,
-        # which is what keeps ENTER *bubbling* — see {#handle_key}.
+        # which is what keeps ENTER *bubbling* — see {#handle_key?}.
         editor.on_enter = callback && lambda do
-          commit
+          commit_and_notify
           callback.call
         end
       end
@@ -158,8 +170,8 @@ module Tuile
       # @param key [String]
       # @return [Boolean] whatever `super` returns — committing never consumes
       #   the key.
-      def handle_key(key)
-        commit if key == Keys::ENTER
+      def handle_key?(key)
+        commit_and_notify if key == Keys::ENTER
         super
       end
 
@@ -175,11 +187,11 @@ module Tuile
       def active=(flag)
         was = active?
         super
-        commit if was && !active?
+        commit_and_notify if was && !active?
       end
 
       # @return [void]
-      def on_focus
+      def handle_focus
         super
         # The editor is what actually edits, so it takes the focus this field was
         # given — the field itself has no keys of its own.
@@ -204,6 +216,21 @@ module Tuile
       # @return [void]
       def commit = nil
 
+      # Whether an edit of the buffer fires {HasValue#on_value_change} as it
+      # happens. `true` here, which is right wherever every buffer state is a
+      # value the user might mean: an {IntegerField} passing through `4` on the
+      # way to `42` really does hold 4 for that keystroke. A field whose
+      # grammar is **not prefix-closed** answers `false` and lets the notice
+      # settle onto the commit gestures instead ({DateField}, `D_date_field`).
+      #
+      # Only the *push* settles: {HasValue#value} stays a live parse of the
+      # buffer either way. And overriding this is half the job — {#commit} is
+      # covered here, but the field must fire from its own `value=` too, or a
+      # programmatic write and an Up/Down step go unannounced until the next
+      # commit.
+      # @return [Boolean]
+      def notify_on_edit? = true
+
       # Called whenever the editor's buffer changes, however the characters
       # arrived — a typed key, a paste, or a {#value=} of this field's own. It
       # is named for the *editor*, not for the user, because those last two are
@@ -211,7 +238,7 @@ module Tuile
       # the *previous* buffer, as a field latching whether its input has settled
       # must ({HasBadInput}).
       # @return [void]
-      def on_editor_change = nil
+      def handle_editor_change; end
 
       # Places the editor across the whole rect; override to reserve cells for a
       # face of your own.
@@ -227,6 +254,15 @@ module Tuile
 
       private
 
+      # Every commit gesture runs through here, so a field holding its notice
+      # ({#notify_on_edit?}) announces from one place rather than three; the
+      # diff guard makes the call free for a field that fired on the way in.
+      # @return [void]
+      def commit_and_notify
+        commit
+        fire_if_changed
+      end
+
       # Re-emits {HasValue#on_value_change}, but only when {#value} differs from
       # the last one fired — so a buffer edit that leaves the value alone
       # (`"7"`→`"07"`) stays silent.

data/lib/tuile/component/button.rb

@@ -9,7 +9,7 @@ module Tuile
     #
     # Buttons are tab stops — Tab and Shift+Tab will land on them as part of
     # the standard focus cycle. Click-to-focus also works via the inherited
-    # {Component#handle_mouse}.
+    # {Component#handle_mouse_down?}.
     #
     # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
     # show `[ caption ]` — that natural width is `caption.display_width + 4`.
@@ -38,7 +38,7 @@ module Tuile
 
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         case key
         when Keys::ENTER, " "
           @on_click&.call
@@ -52,7 +52,7 @@ module Tuile
       # columns, clipped to {#rect}. Both the focus highlight and the click hit
       # test use it, so a click on the blank tail of an over-wide rect — or on a
       # lower row, when the rect is taller than one — does not fire {#on_click}.
-      # It still *focuses*: {Component#handle_mouse}'s click-to-focus is ungated
+      # It still *focuses*: {Mouse::Router}'s click-to-focus is ungated
       # by geometry. Same rule as {Checkbox#extent}, which documents the two
       # traps behind it.
       # @return [Size]
@@ -60,13 +60,13 @@ module Tuile
 
       # Fires {#on_click} on a left click within {#extent}; `super` runs first, so
       # a click anywhere in {#rect} still focuses.
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left && extent_rect.contains?(event.point)
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         @on_click&.call
+        true
       end
 
       # @return [void]

data/lib/tuile/component/checkbox.rb

@@ -89,7 +89,7 @@ module Tuile
       #
       # Both the focus highlight and the click hit test use it, so a click on the
       # blank tail — or on a lower row, when the rect is taller than one — does
-      # not toggle. It still *focuses*: {Component#handle_mouse}'s click-to-focus
+      # not toggle. It still *focuses*: {Mouse::Router}'s click-to-focus
       # is ungated by geometry, and the tail is the field's own row.
       #
       # The extent ignores {Component#bg_color}: an inherited tint paints the dead
@@ -102,22 +102,22 @@ module Tuile
       # to an ancestor.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         return false unless [" ", Keys::ENTER].include?(key)
 
         toggle
         true
       end
 
-      # Toggles on a left click within {#extent}; `super` runs first, so a click
-      # anywhere in {#rect} still focuses.
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left && extent_rect.contains?(event.point)
+      # Toggles on a left press; a press on the dead tail past {#extent} focuses
+      # the checkbox without reaching here.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         toggle
+        true
       end
 
       # @return [void]

data/lib/tuile/component/checkbox_group.rb

@@ -83,9 +83,10 @@ module Tuile
 
       # The composed {List}: an app may *tune* it — its scrollbar, its cursor,
       # `show_cursor_when_inactive` — but never replace it, since this group's
-      # renderer and selection are wired into this one. Those knobs are {List}
-      # concepts rather than group concepts, which is why they are reached here
-      # instead of forwarded (`DECISIONS.md` `D_wrapping_field`).
+      # renderer and selection are wired into this one (`design/decisions.md`
+      # `D_has_content`). Those knobs are {List} concepts rather than group
+      # concepts, which is why they are reached here instead of forwarded
+      # (`D_wrapping_field`).
       # @return [List]
       attr_reader :list
 
@@ -97,7 +98,7 @@ module Tuile
       end
 
       # @return [void]
-      def on_focus
+      def handle_focus
         super
         # The list is what the arrows drive, so it takes the focus this group
         # was given; the group itself claims only Space.
@@ -152,7 +153,7 @@ module Tuile
       # neither of us wants bubbles on to an ancestor.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         return false unless key == " "
 
         toggle_at(list.cursor.position)

data/lib/tuile/component/combo_box.rb

@@ -30,9 +30,16 @@ module Tuile
     # The dropdown is a {ListDropdown}, tinted to read as a floating panel; see
     # it for the theming knob.
     #
+    # == The inner field is private machinery
+    # It has no public accessor: its buffer is the *query*, so swapping the field
+    # would break the filtering. What is worth reaching is re-exposed here
+    # ({#placeholder}, {#cursor_position}); a **spec** reaches the field itself:
+    #
+    #   field = Testing.get(Component::TextField, in: combo)
+    #   field.text = "ap"          # type a query without a real loop
+    #
     # UI-thread-confined, like every component (see {Screen}).
     class ComboBox < Component
-      include HasContent
       include HasValue
       include HasPlaceholder
 
@@ -47,16 +54,16 @@ module Tuile
         @filtered = []
         @suppressing_filter = false
 
-        field = TextField.new
+        @field = TextField.new
         # One widget, one surface: this field paints no well of its own, so the
         # composed field's own bg_color reaches the cells the field paints.
-        field.bg_color = BG_INHERIT
-        field.on_change = ->(_text) { refill unless @suppressing_filter }
+        @field.bg_color = BG_INHERIT
+        @field.on_change = ->(_text) { refill unless @suppressing_filter }
         # ESC is the one key this combo wants that the field consumes itself, so
-        # it cannot arrive by bubbling the way {#handle_key}'s do. With no menu
+        # it cannot arrive by bubbling the way {#handle_key?}'s do. With no menu
         # open it keeps the field's own meaning: cancel text entry.
-        field.on_escape = -> { @overlay.open? ? dismiss_menu : screen.focused = nil }
-        self.content = field
+        @field.on_escape = -> { @overlay.open? ? dismiss_menu : screen.focused = nil }
+        add_child(@field, at: 0)
 
         @overlay = ListDropdown.new
         # Outside-click dismissal spans the owner chain, so a click on this
@@ -105,30 +112,39 @@ module Tuile
 
       # @return [Point, nil] the field's caret position (the combo delegates the
       #   hardware cursor to its field).
-      def cursor_position = content.cursor_position
+      def cursor_position = field.cursor_position
 
       # The hint the inner field paints while empty ({HasPlaceholder}) — for a
       # combo that means while nothing is selected *and* nothing is typed, so it
       # reads as a prompt for the query: `"type to filter"`.
       # @return [String, nil]
-      def placeholder = content.placeholder
+      def placeholder = field.placeholder
 
       # @param text [String, nil]
       # @return [void]
       # @raise [TypeError] unless `text` is a String or nil.
       def placeholder=(text)
-        content.placeholder = text
+        field.placeholder = text
       end
 
-      # Re-anchors the (open) dropdown after {HasContent#rect=} has resized the
-      # field via {#layout}.
+      # Resizes the field and re-anchors the dropdown if it is open.
       # @param new_rect [Rect]
       # @return [void]
       def rect=(new_rect)
         super
+        # One row, or none at all when the combo itself was given none — a
+        # starved parent must not hand out a rect it doesn't own.
+        field.rect = Rect.new(rect.left, rect.top, [rect.width - 1, 0].max, [rect.height, 1].min)
         anchor if @overlay.open?
       end
 
+      # @return [void]
+      def handle_focus
+        super
+        # The field is what edits, so it takes the focus the combo was given.
+        screen.focused = field if field.focusable?
+      end
+
       # Closes the dropdown and reverts an uncommitted query when the combo
       # leaves the focus chain — so tabbing away doesn't strand an open menu or
       # a half-typed filter. Safe against re-entrancy: focus never sits inside
@@ -156,7 +172,7 @@ module Tuile
       # {AbstractStringField#on_escape} instead.
       # @param key [String]
       # @return [Boolean] true if consumed.
-      def handle_key(key)
+      def handle_key?(key)
         if @overlay.open?
           return true if @overlay.move(key)
           return false unless key == Keys::ENTER
@@ -170,15 +186,16 @@ module Tuile
         true
       end
 
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        if content.rect.contains?(event.point)
-          content.handle_mouse(event)
-        elsif event.button == :left && rect.contains?(event.point) # the ▾ cell
-          content.focus
-          @overlay.open? ? close_menu : open_menu
-        end
+      # Toggles the dropdown on a left press on the ▾ cell — the only cell of
+      # this component's own that is not the field's.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
+
+        field.focus
+        @overlay.open? ? close_menu : open_menu
+        true
       end
 
       # @return [void]
@@ -203,19 +220,17 @@ module Tuile
       # @return [Size]
       def extent = Size.new(rect.width, 1)
 
-      protected
-
-      # Field spans the row bar the last column, which the `▾` occupies
-      # ({HasContent} layout hook). One row, or none at all when the combo itself
-      # was given none — a starved parent must not hand out a rect it doesn't own.
-      # @param field [Component]
+      # Declines the default's blank: `field` covers every column of the face but
+      # the last, and this combo paints the `▾` into that one, so blanking would
+      # only dirty a cell it is about to repaint (`D_progress_bar`).
       # @return [void]
-      def layout(field)
-        field.rect = Rect.new(rect.left, rect.top, [rect.width - 1, 0].max, [rect.height, 1].min)
-      end
+      def clear_inside_extent = nil
 
       private
 
+      # @return [TextField] the inner field, holding the query.
+      attr_reader :field
+
       # Dismisses the dropdown and puts the current value's label back in the
       # field, undoing an uncommitted query.
       # @return [void]
@@ -229,7 +244,7 @@ module Tuile
       # when there are none.
       # @return [void]
       def refill
-        @filtered = matching(content.text)
+        @filtered = matching(field.text)
         if @filtered.empty?
           close_menu
         else
@@ -273,7 +288,7 @@ module Tuile
       # Sets the field's text without triggering a refilter — for programmatic
       # value changes and query reverts, which must not spring the dropdown.
       # Every programmatic write to the field goes through here; a direct
-      # `content.text =` reaches the field's `on_change` and pops the dropdown
+      # `field.text =` reaches the field's `on_change` and pops the dropdown
       # open on a {#value=} the user never asked to browse.
       # Parks the caret at the end: `text=` only *clamps* the caret, so a
       # shorter query replaced by a longer label would otherwise strand it
@@ -282,8 +297,8 @@ module Tuile
       # @return [void]
       def sync_field(text)
         @suppressing_filter = true
-        content.text = text
-        content.caret = content.text.length
+        field.text = text
+        field.caret = field.text.length
       ensure
         @suppressing_filter = false
       end

data/lib/tuile/component/confirm_window.rb

@@ -44,7 +44,7 @@ module Tuile
     # There is deliberately no content slot: the body is prose ({#message=}
     # takes a component for the rare rich body, but the dialog then cannot
     # measure it). A dialog collecting *input* is not a confirm dialog — build a
-    # `Popup.new(content: your_layout)`. See `DECISIONS.md` `D_confirm_window`
+    # `Popup.new(content: your_layout)`. See `design/decisions.md` `D_confirm_window`
     # for the API rationale.
     class ConfirmWindow < Window
       # Keys handed to the message body from anywhere in the dialog, so it
@@ -221,9 +221,11 @@ module Tuile
       end
 
       # Focus lands on the first button rather than cascading into the message
-      # body, which sits before the button row in the tree.
+      # body, which sits before the button row in the tree. `super` is reached
+      # only when there is no button to take it: {HasContent#handle_focus} *is*
+      # the cascade this override exists to skip.
       # @return [void]
-      def on_focus
+      def handle_focus
         first = @actions.keys.first
         if first.nil?
           super
@@ -239,11 +241,11 @@ module Tuile
       # before this runs.
       # @param key [String]
       # @return [Boolean] true if the key was handled.
-      def handle_key(key)
+      def handle_key?(key)
         case key
         when Keys::LEFT_ARROW then return focus_button_step(-1)
         when Keys::RIGHT_ARROW then return focus_button_step(1)
-        when *BODY_SCROLL_KEYS then return @body_slot.content&.handle_key(key) || false
+        when *BODY_SCROLL_KEYS then return @body_slot.content&.handle_key?(key) || false
         end
 
         target = @mnemonics[key.downcase]

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 change
+    #   field.on_value_change = ->(d) { puts d.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
@@ -63,6 +63,19 @@ module Tuile
     # `20`, `202` stay quiet, leaving the field (or pressing ENTER) reddens what
     # did not parse, and the next edit clears it again.
     #
+    # == The value notice waits for the same gesture
+    # A prefix of a date can also parse *cleanly*: typing `1.1.2024` into a
+    # `%d.%m.%Y` field passes through `1.1.2`, a perfectly good 1st of January
+    # in the year 2. So {HasValue#on_value_change} does not fire per keystroke,
+    # but when the user leaves the field or presses ENTER — and a form
+    # recalculating from it never sees that year 2.
+    #
+    # {#value} does *not* wait: it is a live parse of the buffer at every
+    # moment, so a save gate reached without leaving the field reads the date
+    # on screen. Nor does a change nobody had to type — a {#value=}, an Up/Down
+    # step, a {#clear} and a reparse under new {#formats} all fire as they
+    # happen.
+    #
     # == Implementation details
     # - **The buffer is the single source of truth.** {#value} is a parse of it,
     #   recomputed on read — so {#formats=} and {#calendar_start=} can change the
@@ -135,6 +148,9 @@ module Tuile
       def value=(new_value)
         editor.text = new_value.nil? ? "" : new_value.strftime(formats.first)
         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
       end
 
       # `nil`, not `""`: a date field with no parseable date is empty.
@@ -244,6 +260,12 @@ module Tuile
         settle(true)
       end
 
+      # `false`: a prefix of a date can parse cleanly (`1.1.2` for `1.1.2024`),
+      # so the notice settles onto the commit gestures, exactly as the ink
+      # does. The class docs carry the case.
+      # @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
@@ -255,12 +277,15 @@ module Tuile
       # An edit is the user having another go, so the well goes quiet again
       # until the next commit gesture.
       # @return [void]
-      def on_editor_change = settle(false)
+      def handle_editor_change
+        super
+        settle(false)
+      end
 
       # Re-derives the hint (which was *pushed* into the editor, so a repaint
       # alone would keep the old one) and rewrites a buffer that still parses.
       # @return [void]
-      def on_locale_changed
+      def handle_locale_changed
         super
         # Both overridden: this field follows no session convention.
         return if @formats && @calendar_start