tuile 0.15.0 → 0.17.0

data/lib/tuile/component/abstract_string_field.rb

@@ -9,9 +9,9 @@ module Tuile
     # drag this String-typed `text`/`value` seam onto its face alongside the
     # real typed one.
     #
-    # Holds the shared state — a mutable {#text} buffer, a {#caret} index,
-    # {#on_change} and {#on_escape} callbacks — and the keyboard machinery
-    # that single-line and multi-line inputs both need: ESC handling,
+    # Holds the shared state — a mutable {#text} buffer, a {#caret} index, the
+    # {#on_escape} slot — and the keyboard machinery that single-line and
+    # multi-line inputs both need: ESC handling,
     # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, CTRL+W
     # word-delete, and the `tab_stop?` flag (`focusable?` comes from
     # {HasValue}).
@@ -21,24 +21,24 @@ module Tuile
     # forward onto the enclosing cluster's end, and every edit steps by a whole
     # cluster:
     #
-    #   f.text  = "e\u{0301}x"   # a decomposed e-acute then "x": 3 chars, 2 glyphs
+    #   f.value = "e\u{0301}x"   # a decomposed e-acute then "x": 3 chars, 2 glyphs
     #   f.caret = 1              # into the middle of the e-acute …
     #   f.caret                  # => 2, its end — where the caret already drew
-    #   f.handle_key(Keys::BACKSPACE)
+    #   f.handle_key?(Keys::BACKSPACE)
     #   f.text                   # => "x": the whole glyph went, not its accent
     #
     # Insertion stays character-native, so `String#insert` merges a typed
-    # combining mark into its base; {#text=}'s snap covers the case where that
+    # combining mark into its base; {#set_value}'s snap covers the case where that
     # re-segments the text around the caret.
     #
     # Subclasses implement the layout-specific pieces ({#cursor_position},
     # {#repaint}) and add their own keys (HOME/END, ENTER, UP/DOWN,
     # printable insertion) by overriding the protected
-    # {#handle_text_input_key} hook — `super` falls through to the common
+    # {#handle_text_input_key?} hook — `super` falls through to the common
     # navigation handling.
     #
     # == Customizing a field is subclassing it, and there are two seams
-    # To change what **keys** do, override {#handle_text_input_key}; to
+    # To change what **keys** do, override {#handle_text_input_key?}; to
     # constrain what the buffer may **hold**, override {#insert_text}, which
     # every insertion runs through — typed, pasted, or the ENTER newline:
     #
@@ -46,7 +46,7 @@ module Tuile
     #     protected
     #
     #     # ENTER submits instead of falling through to the parent.
-    #     def handle_text_input_key(key)
+    #     def handle_text_input_key?(key)
     #       return super unless key == Keys::ENTER
     #
     #       submit(text)
@@ -66,17 +66,19 @@ module Tuile
     # share one slot, and a filter written on a *key* callback let the same
     # characters in through a paste (`D_input_filters`, book ch7).
     #
-    # The mutation pipeline is a template method: {#text=} and {#caret=}
-    # detect no-ops, mutate state, fire {#on_change}, and invalidate.
+    # The mutation pipeline is a template method: {#set_value} and {#caret=}
+    # detect no-ops, mutate state, fire {HasValue#on_value_change}, and invalidate.
+    # Typing, a paste and the deleting keys write with `from_user: true`, every
+    # other write with `false` ({HasValue::ValueChangeEvent#from_user?}).
     # Subclasses inject their own behavior via four protected hooks:
     #
     # - {#insert_text} — **the one filter seam**: every insertion runs through
     #   it, typed or pasted, so what the buffer may hold is decided here.
-    # - {#preprocess_text} — filter for a whole assignment to {#text=},
+    # - {#preprocess_text} — filter for a whole assignment to {#set_value},
     #   which insertion does *not* pass through.
     # - {#preprocess_paste} — sanitizer for {#handle_paste}, run before the
     #   clipboard reaches {#insert_text} ({TextField} keeps its first line).
-    # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
+    # - {#handle_text_mutated} / {#handle_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
     class AbstractStringField < Component
@@ -86,24 +88,41 @@ module Tuile
         super
         @text = +""
         @caret = 0
-        @on_change = nil
-        @on_value_change = nil
-        @on_escape = method(:default_on_escape)
+        @escape_clears_focus = true
+        # Unconditional on purpose: a field used as the face of a composed one
+        # ({ComboBox}, {IntegerField} …) is *told* to drop its well with
+        # {ComponentBackground::INHERIT} — a second well would make the
+        # composer's own bg_color inert over the very cells this field paints.
+        bg.default_color = ComponentBackground::INPUT_WELL
       end
 
       # @return [String] current text contents.
       attr_reader :text
 
-      # A text component's value *is* its text: {#value}/{#value=} are the
-      # {HasValue} seam over the same buffer as {#text}/{#text=}, so a form can
-      # drive it alongside typed fields. `text` stays the text-native name.
+      # A text component's value *is* its text: {#value} reads the same buffer
+      # as {#text}, and {#set_value} is its one writer.
       # @return [String]
       def value = text
 
+      # Replaces the text. Runs {#preprocess_text} first, then clamps the caret
+      # to the new text and snaps it onto a cluster boundary of it. Fires
+      # {HasValue#on_value_change} only on a real change — never on {#caret=}.
+      #
+      #   field.value = "admin"
+      #   field.caret = field.text.length   # the caret is clamped, never moved to the end
+      #
       # @param new_value [String, #to_s]
+      # @param from_user [Boolean] see {HasValue#set_value}.
       # @return [void]
-      def value=(new_value)
-        self.text = new_value.to_s
+      def set_value(new_value, from_user:)
+        new_value = preprocess_text(new_value)
+        return if @text == new_value
+
+        @text = +new_value
+        @caret = snap_to_cluster(@caret.clamp(0, @text.length))
+        handle_text_mutated
+        invalidate
+        on_value_change.fire(HasValue::ValueChangeEvent.new(source: self, value: @text, from_user:))
       end
 
       # `""` (not `nil`): a text field is empty when its buffer is blank.
@@ -114,42 +133,40 @@ module Tuile
       #   and always on a grapheme-cluster boundary (see the class doc).
       attr_reader :caret
 
-      # Optional callback fired whenever {#text} changes. Receives the new text
-      # as a single argument. Not fired by {#caret=} (text unchanged) and not
-      # fired when a setter is a no-op.
-      # @return [Proc, Method, nil] one-arg callable, or nil.
-      attr_accessor :on_change
-
-      # Callback fired when ESC is pressed. Defaults to a closure that clears
-      # focus (`screen.focused = nil`) so ESC visibly cancels text entry instead
-      # of bubbling to the parent — and, in particular, instead of reaching the
-      # screen's default ESC-to-quit handler. Set to nil to let ESC fall through
-      # to the parent again; set to any other callable to replace the default.
-      # @return [Proc, Method, nil] no-arg callable, or nil.
-      attr_accessor :on_escape
+      # What {#on_escape} fires.
+      #
+      # @!attribute [r] source
+      #   @return [AbstractStringField] the field ESC reached.
+      EscapeEvent = Data.define(:source) { include Tuile::Event }
+
+      # @!method on_escape
+      #   Fired with an {EscapeEvent} when ESC is pressed, after
+      #   {#escape_clears_focus} has had its say. Append to react as well as
+      #   blur; turn that flag off first to react *instead*:
+      #
+      #     field.escape_clears_focus = false
+      #     field.on_escape << method(:close_search)
+      #
+      #   **Empty means the field declines ESC** — but only while
+      #   {#escape_clears_focus} is off too, since a field that blurs has
+      #   handled the key. With both, ESC bubbles to the parent, and on to the
+      #   screen's ESC-to-quit.
+      #   @return [Listeners]
+      listener :on_escape
+
+      # Whether ESC clears focus (`true` by default), so text entry visibly
+      # cancels instead of quitting the app. It runs before {#on_escape} fires,
+      # and it — not a listener an app must remove by identity — is the whole
+      # representation of the default, so turning it off is the one way to give
+      # ESC another meaning. See `D_escape_opt_out`.
+      # @return [Boolean]
+      attr_accessor :escape_clears_focus
 
       def tab_stop? = true
 
-      # Sets the text. Runs {#preprocess_text} first (subclasses may filter or
-      # truncate). Caret is clamped to the new text length, then snapped back
-      # onto a cluster boundary of the *new* text. Fires {#on_change} only on a
-      # real change.
-      # @param new_text [String]
-      def text=(new_text)
-        new_text = preprocess_text(new_text)
-        return if @text == new_text
-
-        @text = +new_text
-        @caret = snap_to_cluster(@caret.clamp(0, @text.length))
-        on_text_mutated
-        invalidate
-        @on_change&.call(@text)
-        on_value_change&.call(@text)
-      end
-
       # Clamps to `0..text.length`, then snaps forward onto a grapheme-cluster
       # boundary, so an index that fell inside a cluster reads back as that
-      # cluster's end. Fires the {#on_caret_mutated} hook for subclasses (e.g.
+      # cluster's end. Fires the {#handle_caret_mutated} hook for subclasses (e.g.
       # {TextArea} scrolls).
       # @param new_caret [Integer]
       def caret=(new_caret)
@@ -157,27 +174,26 @@ module Tuile
         return if @caret == new_caret
 
         @caret = new_caret
-        on_caret_mutated
+        handle_caret_mutated
         invalidate
       end
 
-      # Handles a key, by delegating to the {#handle_text_input_key} hook a
-      # subclass overrides. Dispatch ({ScreenPane#handle_key}) only routes keys
+      # Handles a key, by delegating to the {#handle_text_input_key?} hook a
+      # subclass overrides. Dispatch ({ScreenPane#handle_key?}) only routes keys
       # here when this input is on the focus chain, so there is no {#active?}
       # gate.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key) = handle_text_input_key(key)
+      def handle_key?(key) = handle_text_input_key?(key)
 
-      # Inserts pasted text at the caret as **one** mutation, so {#on_change}
-      # fires once for the whole paste rather than once per character.
+      # Inserts pasted text at the caret as **one** mutation, so
+      # {HasValue#on_value_change} fires once for the whole paste rather than
+      # once per character.
       # {#preprocess_paste} filters it first.
       # @param text [String]
-      # @return [Boolean] always true — a field consumes every paste: an empty
-      #   one, and one its {#insert_text} rejects wholesale.
+      # @return [void]
       def handle_paste(text)
         insert_text(preprocess_paste(text))
-        true
       end
 
       protected
@@ -212,8 +228,10 @@ module Tuile
       # (a date — `"2020-13-45"` is well-formed at every character) reports bad
       # input rather than filtering it (`D_input_filters`, book ch7).
       #
-      # {#text=} does *not* pass through here: only user input is filtered, so a
-      # programmatic {HasValue#value=} may still write what no key types.
+      # {#set_value} does *not* pass through here: only user input is filtered,
+      # so a programmatic write may still hold what no key types. The same line
+      # decides the origin: an insertion is the user's, so it writes with
+      # `from_user: true`.
       # @param str [String]
       # @return [Boolean] true if the text changed.
       def insert_text(str)
@@ -221,25 +239,11 @@ module Tuile
 
         new_text = @text.dup.insert(@caret, str)
         @caret += str.length
-        self.text = new_text
+        set_value(new_text, from_user: true)
         true
       end
 
-      # The field's background well, looked up from the current {Screen#theme}
-      # at paint time: {Theme#active_bg_color} while this input is on the active
-      # (focus) chain, {Theme#input_bg_color} otherwise — visibly a field either
-      # way, distinctly highlighted when focused. An app overrides the pair by
-      # setting {Component#bg_color}, which wins over this.
-      #
-      # Unconditional on purpose. A field used as the face of a composed one
-      # ({Component::ComboBox}, {Component::IntegerField} …) is *told* to drop
-      # its well — that widget assigns {Component::BG_INHERIT} at construction,
-      # since it owns the surface and a second well would make its own
-      # {Component#bg_color} inert over the very cells this field paints.
-      # @return [Color]
-      def default_bg_color = active? ? screen.theme.active_bg_color : screen.theme.input_bg_color
-
-      # Input filter for a whole assignment to {#text=}. Nothing overrides it
+      # Input filter for a whole assignment to {#set_value}. Nothing overrides it
       # today; a subclass that does is filtering the *programmatic* setter, not
       # user input — that is {#insert_text}.
       # @param new_text [String]
@@ -256,18 +260,18 @@ module Tuile
       def columns_of(str) = str.each_grapheme_cluster.sum { |g| Buffer.display_width(g) }
 
       # Hook called after {#text} has been mutated, before invalidation /
-      # {#on_change}. Default no-op. Subclasses use this to invalidate caches
-      # ({TextArea}'s wrap cache) and update derived state.
+      # {HasValue#on_value_change}. Default no-op. Subclasses use this to
+      # invalidate caches ({TextArea}'s wrap cache) and update derived state.
       # @return [void]
-      def on_text_mutated; end
+      def handle_text_mutated; end
 
       # Hook called after {#caret} has been mutated, before invalidation.
       # Default no-op. Subclasses use this to keep the caret visible
       # ({TextArea}'s vertical scroll).
       # @return [void]
-      def on_caret_mutated; end
+      def handle_caret_mutated; end
 
-      # Dispatch hook for {#handle_key}. Handles ESC and the editing keys that
+      # Dispatch hook for {#handle_key?}. Handles ESC and the editing keys that
       # have identical semantics in single-line and multi-line inputs:
       # LEFT/RIGHT arrows (one grapheme cluster per press, so a press always
       # moves), CTRL+LEFT/CTRL+RIGHT for word jumps, and CTRL+W, which deletes
@@ -277,7 +281,7 @@ module Tuile
       # `super` to fall back to the common handling.
       # @param key [String]
       # @return [Boolean] true if the key was handled.
-      def handle_text_input_key(key)
+      def handle_text_input_key?(key)
         case key
         when Keys::LEFT_ARROW then self.caret = cluster_boundary_before(@caret)
         when Keys::RIGHT_ARROW then self.caret = cluster_boundary_after(@caret)
@@ -285,9 +289,10 @@ module Tuile
         when Keys::CTRL_RIGHT_ARROW then self.caret = word_right
         when Keys::CTRL_W then delete_back_to(word_left)
         when Keys::ESC
-          return false if @on_escape.nil?
+          return false if !@escape_clears_focus && on_escape.empty?
 
-          @on_escape.call
+          screen.focused = nil if @escape_clears_focus
+          on_escape.fire(EscapeEvent.new(source: self))
         else
           return false
         end
@@ -301,7 +306,8 @@ module Tuile
       def delete_before_caret = delete_back_to(cluster_boundary_before(@caret))
 
       # Removes the text between `index` and the caret, leaving the caret at
-      # `index` — one mutation, so {#on_change} fires once.
+      # `index` — one mutation, so {HasValue#on_value_change} fires once, as the
+      # user's: every caller is a deleting key.
       #
       # `index` is snapped forward onto a grapheme-cluster boundary, so a
       # caller may compute it by counting characters.
@@ -314,7 +320,7 @@ module Tuile
         new_text = @text.dup
         new_text.slice!(start...@caret)
         @caret = start
-        self.text = new_text
+        set_value(new_text, from_user: true)
       end
 
       # Removes the whole grapheme cluster at the caret.
@@ -324,7 +330,7 @@ module Tuile
 
         new_text = @text.dup
         new_text.slice!(@caret...cluster_boundary_after(@caret))
-        self.text = new_text
+        set_value(new_text, from_user: true)
       end
 
       private
@@ -368,13 +374,6 @@ module Tuile
         offset
       end
 
-      # Default {#on_escape} action: clear focus. Component deactivates; user
-      # can re-focus by clicking or tabbing back in.
-      # @return [void]
-      def default_on_escape
-        screen.focused = nil
-      end
-
       # Caret target for ctrl+left: skip whitespace going left, then a run of
       # non-whitespace. Lands at the beginning of the current word, or the
       # beginning of the previous word if already there.

data/lib/tuile/component/abstract_wrapping_field.rb

@@ -12,8 +12,8 @@ module Tuile
     #
     #     def value = Integer(editor.text, 10) rescue nil
     #
-    #     def value=(new_value)
-    #       editor.text = new_value.nil? ? "" : new_value.to_s
+    #     def set_value(new_value, from_user:)
+    #       editor.set_value(new_value.nil? ? "" : new_value.to_s, from_user:)
     #       editor.caret = editor.text.length
     #     end
     #
@@ -37,7 +37,7 @@ module Tuile
     # editor is how a test reaches a state no public setter produces:
     #
     #   editor = Testing.get(Component::TextField, in: field)
-    #   editor.text = "-"          # bad input; field.value still reads nil
+    #   editor.value = "-"         # bad input; field.value still reads nil
     #
     # A knob that is *editor-shaped* rather than a concept of this field's own
     # domain is **not** forwarded, and the subclass sets it on its editor
@@ -55,24 +55,38 @@ module Tuile
     # by ENTER never moves focus at all. Override it to canonicalize a buffer
     # the user typed loosely:
     #
-    #   def commit = (self.value = value unless value.nil?)   # rewrite in the canonical form
+    #   def commit = (set_value(value, from_user: true) unless value.nil?)   # rewrite canonically
     #
     # ENTER is committed and then **left to keep bubbling**, so a scope's
     # 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}).
+    #
+    # == Who made the change
+    # The editor's own event says whether the user moved the buffer, and this
+    # field's notice passes that on: a subclass writes the editor through
+    # {AbstractStringField#set_value} with the `from_user:` it was handed, and
+    # the edit route relays it. The commit gestures announce as the user's —
+    # an approximation for the one commit code can cause, a programmatic
+    # `screen.focused =` moving focus off this field.
+    #
     # == Implementation details
-    # - **{HasValue#value} and {#value=} raise until overridden.** The inherited
+    # - **{HasValue#value} and {#set_value} raise until overridden.** The inherited
     #   pair stores into `@value` and never touches the editor, so a subclass
     #   that defined only one would silently half-work.
     # - **{HasValue#empty_value} is called during construction**, to seed the
     #   change guard, so it must not depend on subclass state that `super` has
     #   not set yet. In practice it is a constant per class.
-    # - **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
-    #   reassigning either.
+    # - **The editor's `on_value_change` and `on_enter` slots carry this field's own
+    #   listeners** — for that guard, and to commit before an app's ENTER handler
+    #   runs. They are lists, so nothing an app adds displaces them; a subclass
+    #   reacting to buffer edits still overrides {#handle_editor_change} (every
+    #   edit), {#set_value} or {#commit}, which run in a defined order.
     # - **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.
     #   {ComboBox} breaks both halves — its text is a transient query and only a
@@ -92,13 +106,19 @@ module Tuile
 
         @editor = editor
         @last_value = empty_value
-        @on_enter = nil
+        # Held so the transition block can unsubscribe the same object it added:
+        # a lambda is only equal to itself.
+        @enter_bridge = lambda do
+          commit_and_notify
+          on_enter.fire(EnterEvent.new(source: self))
+        end
         # One widget, one surface: the editor paints no well of its own, so this
-        # 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
+        # field's well covers it and its bg_color reaches the cells the editor paints.
+        editor.bg_color = ComponentBackground::INHERIT
+        bg.default_color = ComponentBackground::INPUT_WELL
+        editor.on_value_change do |e|
+          handle_editor_change
+          fire_if_changed(from_user: e.from_user?) if notify_on_edit?
         end
         add_child(editor, at: 0)
       end
@@ -107,19 +127,27 @@ module Tuile
       # @raise [NotImplementedError] unless the subclass overrides it.
       def value = raise(NotImplementedError, "#{self.class} must implement value")
 
-      # Writes `new_value` into the editor's buffer.
+      # Writes `new_value` into the editor's buffer, passing `from_user` on to
+      # {AbstractStringField#set_value}.
       # @param new_value [Object]
+      # @param from_user [Boolean] see {HasValue#set_value}.
       # @return [void]
       # @raise [NotImplementedError] unless the subclass overrides it.
-      def value=(new_value)
-        raise(NotImplementedError, "#{self.class} must implement value=")
+      def set_value(new_value, from_user:)
+        raise(NotImplementedError, "#{self.class} must implement set_value")
       end
 
       # Empties the *input*, not just the value — a field holding bad input
       # 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(from_user: false)
+      end
 
       # @return [String, nil] the hint the editor paints while empty
       #   ({HasPlaceholder}).
@@ -132,34 +160,36 @@ module Tuile
         editor.placeholder = text
       end
 
-      # @return [Proc, Method, nil] fired when ENTER is pressed, *after*
-      #   {#commit}; see {TextField#on_enter}.
-      attr_reader :on_enter
+      # What {#on_enter} fires.
+      #
+      # @!attribute [r] source
+      #   @return [AbstractWrappingField] the field ENTER reached.
+      EnterEvent = Data.define(:source) { include Tuile::Event }
 
-      # @param callback [Proc, Method, nil]
-      # @return [void]
-      def on_enter=(callback)
-        @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}.
-        editor.on_enter = callback && lambda do
-          commit
-          callback.call
-        end
+      # @!method on_enter
+      #   Fired with an {EnterEvent} when ENTER is pressed, *after* {#commit};
+      #   see {TextField#on_enter}.
+      #
+      #   **Empty means the field declines ENTER**, which keeps it bubbling to
+      #   the scope's default button — see {#handle_key?}. The editor's own slot
+      #   is claimed only while this one is non-empty, by a bridge that commits
+      #   first, so a listener here always reads a committed buffer.
+      #   @return [Listeners]
+      listener :on_enter do |claimed|
+        claimed ? editor.on_enter << @enter_bridge : editor.on_enter.remove(@enter_bridge)
       end
 
       # Commits on ENTER, and leaves the key unconsumed so it keeps bubbling.
       #
-      # The editor declines ENTER whenever {#on_enter} is nil, so the key
+      # The editor declines ENTER whenever {#on_enter} is empty, so the key
       # reaches this field instead — and it must be committed on the way past,
       # or the form default button it is bubbling towards acts on an
       # uncommitted buffer.
       # @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,24 +205,17 @@ 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.
         screen.focused = editor if editor.focusable?
       end
 
-      # @param new_rect [Rect]
-      # @return [void]
-      def rect=(new_rect)
-        super
-        layout(editor)
-      end
-
       protected
 
       # @return [AbstractStringField] the wrapped editor.
@@ -204,39 +227,57 @@ 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 `set_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
+      # arrived — a typed key, a paste, or a {#set_value} of this field's own. It
       # is named for the *editor*, not for the user, because those last two are
       # not input. No-op by default; override it to drop state that describes
       # 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.
-      # @param editor [Component]
       # @return [void]
-      def layout(editor) = (editor.rect = rect)
-
-      # The field well the face sits on — the editor is marked
-      # {Component::BG_INHERIT}, so this one covers it (exactly one well per
-      # widget) and {Component#bg_color} set here reaches the cells it paints.
-      # @return [Color]
-      def default_bg_color = active? ? screen.theme.active_bg_color : screen.theme.input_bg_color
+      def relayout = (editor.rect = local_rect)
 
       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(from_user: true)
+      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.
+      # @param from_user [Boolean] what the write that moved the buffer declared.
       # @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