tuile 0.14.0 → 0.15.0

data/ideas/new-components.md

@@ -50,9 +50,10 @@ That leaves ~46 gaps.
 | ~~Notification~~ | `Popup` + `Ticker` | **built** 2026-08-17 (`D_notification`, book ch7); one non-modal top-right box, N messages, one 3 s ticker retiring the oldest. Corner anchor is its own `reposition` override, so `Popup` was untouched — and the `Popover` extraction still waits for a second *kind* of anchoring |
 | ~~Confirm Dialog~~ | `Popup`+`Window`+`Button` | **built** 2026-08-31 as `ConfirmWindow` (`D_confirm_window`, book ch7); the component is the builder — `#button` plus the `alert`/`confirm`/`yes_no` factories — every button dismisses, MenuBar-shaped mnemonics with `q`/`g`/`G` reserved. The fold-`PickerWindow`-in idea is **rejected**: the two disagree on every semantic that matters (cursor, default, ESC, close-on-pick) and share only API shape |
 | Details → Accordion | `HasContent` | Details is the atom, Accordion the group |
-| ~~Tabs → TabSheet~~ | plain `Component` + the tree API | **built** 2026-08-23 (`D_tabs`, book ch7); a strip (one tab stop, Left/Right, immediate activation) plus a sheet whose `children` are `[strip, pane]`. Neither is `HasValue` — a tab selection is view state — and neither is `HasContent`; hiding a pane means *detaching* it, since Tuile has no visibility flag; the strip owns mutable `Tabs::Tab` handles rather than the `items`/`item_label` shell. Hidden/disabled/closeable tabs, lazy panes and a scrolling strip are deferred, each additive (`D_tabs`) |
+| ~~Tabs → TabSheet~~ | plain `Component` + the tree API | **built** 2026-08-23 (`D_tabs`, book ch7); a strip (one tab stop, Left/Right, immediate activation) plus a sheet whose `children` are `[strip, pane]`. Neither is `HasValue` — a tab selection is view state — and neither is `HasContent`; a `TabSheet` hides a pane by *detaching* it, deliberately — that is what fires the lifecycle hooks on every switch, and it stays the choice now that `Component#visible=` exists (`D_visibility`); the strip owns mutable `Tabs::Tab` handles rather than the `items`/`item_label` shell. Hidden/disabled/closeable tabs, lazy panes and a scrolling strip are deferred, each additive (`D_tabs`) |
 | Popover | `ListDropdown#anchor_to` (extracted 2026-08-12) | generalize the anchored non-modal overlay: `anchor_to` moves down to it and `ListDropdown` inherits it. Build it when the second *kind* of anchoring appears (a point; a right edge that flips) — not the second caller of the same kind. Nothing gates on it today: Menu Bar shipped without it |
 | ~~Menu Bar~~ | `ListDropdown` (+ `anchor_beside`) | **built** 2026-08-24 (`D_menu_bar`, book ch7), mnemonics the same day. Turned out *not* to need the Popover extraction: a focused strip drives a cascade of non-modal `ListDropdown`s the way `Select` drives one, so the additions were a side-anchor method, a highlighted-row rect and a cursor pass-through. Unlimited submenu depth; checkable/disabled items and global-shortcut activation deferred indefinitely |
+| ~~DateField~~ | `AbstractWrappingField` + `HasBadInput` | **built** 2026-09-04 (`D_date_field`, book ch7), after re-tiering out of Tier 2 the same day: the v1 is manual entry only, so the calendar popup it was blocked on became a phase 2 (still Tier 2 below). Value is stdlib `Date`; a per-instance list of strftime `formats`, first whole match winning and `formats.first` written back on blur/ENTER. It filters *nothing* — a date's grammar is not prefix-closed, so the residue is reported through `HasBadInput` — and its empty well derives its own `HasPlaceholder` hint from the primary format. `%y` is rejected outright and the calendar is proleptic Gregorian, not Ruby's `Date::ITALY` |
 | Slider | `draw_line` | arrows/PgUp; 25.2 also has a two-thumb *range* variant |
 | Breadcrumbs | `Label`/`StyledString` | clickable path segments |
 | Markdown | `TextView` + `StyledString` | Markdown subset → styled text; high value on a TTY |
@@ -62,9 +63,9 @@ That leaves ~46 gaps.
 | Component | Blocked on |
 |---|---|
 | **Grid** (the flagship gap) | column model + renderer strategies + typed items + horizontal scroll (L) |
-| Form Layout | a field label/helper seam (Vaadin's `HasLabel`) — Tuile fields carry no caption |
-| Email Field | a validation seam (`HasValidation`: invalid state + error line) |
-| Date / Time / DateTime Picker | calendar-grid popup over Popover (L) |
+| Form Layout | a field label/helper seam (Vaadin's `HasLabel`) — Tuile fields carry no caption by decision (`D_caption_ownership`), so the seam is the layout's own cells: `ideas/form-layout.md` |
+| Email Field | nothing, per `D_bad_input` — its value *is* its input, so it has no bad-input state and contributes only a packaged regex; **re-tiered toward reject** |
+| Calendar grid for `DateField`, and the ~~Time~~ / DateTime twins | the grid needs the calendar popup over Popover (L). It is **phase 2** of a field that already ships (`D_date_field`, Tier 1 above), so nothing is blocked on it: a `DateField` is fully usable by typing, and the grid is additive — a second way to set the same `value`, placed with `ListDropdown#anchor_to`. Two things it inherits rather than re-decides: the month names it paints are the locale question of `ideas/locale.md`, and `PageUp`/`PageDown` stepping a month is deferred there too. The Time / DateTime twins no longer wait on that seam — it shipped (`D_locale`) — and `TimeField` shipped under `D_time_field` (2026-09-05) with **no** picker dropdown: a list of times carries no information a user lacks, so it fails the test the calendar grid passes (`D_mouse`). PageUp/PageDown step an hour instead, and its phase 2 is segment-aware Up/Down (the Qt / `dialog --timebox` model), shared with `DateField` |
 | Multi Select Combo Box | Checkbox Group + ComboBox |
 | Split Layout → Master Detail Layout | mouse **motion/drag**: Tuile runs X10 mode 1000 (press only, no release, no motion) |
 | Virtual List | a lazy data-provider strategy on `List` |
@@ -97,8 +98,27 @@ file when its cluster comes up:
    foundation. A future Grid should reuse its `Fixed`/`Percent`/`Expand`
    constraints per row and column rather than invent a second vocabulary.
 2. **Field label + helper text seam** → Form Layout. Note this is what Form
-   Layout is actually blocked on — the layout half now exists.
-3. **Validation seam** → Email Field, forms generally.
+   Layout is actually blocked on — the layout half now exists. Designed
+   2026-09-03 and **half shipped the same day**: the caption goes to the layout
+   (fields do *not* include `HasCaption` — `D_caption_ownership`), and the error
+   *verdict* stays on the field as `Component::HasValidation` (one member,
+   `error_message`, `HasValue` includes it, painted as a red *well* —
+   `D_has_validation`). What is left is the container that reads the *message*
+   off the field and paints it inline-right, plus the required marker and helper
+   text: `ideas/form-layout.md`. Items 2 and 3 turn out to be the same seam cut
+   in two — this half is the *geometry*, item 3 is the *signals*.
+3. **Validation seam** → forms generally. Designed 2026-09-03 and split three
+   ways. The field-side channel **shipped the same day**: `HasBadInput`
+   (`D_bad_input`) holds the one fact only the field can know, because
+   `on_value_change` is a diff over values and every unrepresentable input
+   collapses onto the same one, and `on_blur` — the commit point it wanted —
+   shipped 2026-09-04 (`D_on_blur`); only the push notice is still deferred, for
+   want of a consumer. Still open: `ideas/binder.md`
+   (the consumer, and the four-layer model/transformations/value/input
+   vocabulary the whole cluster now uses). The `HasValidation` half **shipped
+   the same day** as well (`D_has_validation`), so what is left of item 2's note
+   is the container that paints the message. `Date Picker` is the component that
+   actually forces it; Email Field is re-tiered toward *reject*.
 4. **Anchored Popover extraction** → pickers, Tooltip. **No longer gates Menu
    Bar** — `D_menu_bar` argues the side-anchor is a sibling method on
    `ListDropdown`, since both callers still wrap a `List`; the extraction's

data/lib/tuile/component/abstract_string_field.rb

@@ -12,8 +12,9 @@ module Tuile
     # 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,
-    # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, and the
-    # `tab_stop?` flag (`focusable?` comes from {HasValue}).
+    # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, CTRL+W
+    # word-delete, and the `tab_stop?` flag (`focusable?` comes from
+    # {HasValue}).
     #
     # {#caret} counts *characters* into {#text} but may only sit *between*
     # grapheme clusters — the glyphs a terminal draws. Both write sites snap it
@@ -36,14 +37,45 @@ module Tuile
     # {#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
+    # constrain what the buffer may **hold**, override {#insert_text}, which
+    # every insertion runs through — typed, pasted, or the ENTER newline:
+    #
+    #   class HexField < TextField
+    #     protected
+    #
+    #     # ENTER submits instead of falling through to the parent.
+    #     def handle_text_input_key(key)
+    #       return super unless key == Keys::ENTER
+    #
+    #       submit(text)
+    #       true
+    #     end
+    #
+    #     # Hex digits only — and a paste of "12zz" lands nothing, not "12".
+    #     def insert_text(str)
+    #       return false unless @text.dup.insert(@caret, str).match?(/\A\h*\z/)
+    #
+    #       super
+    #     end
+    #   end
+    #
+    # Both compose through `super`, which is why they are overrides rather than
+    # the callback slot this class carried until 0.15.0: two behaviors could not
+    # 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.
-    # Subclasses inject their own behavior via two protected hooks:
+    # Subclasses inject their own behavior via four protected hooks:
     #
-    # - {#preprocess_text} — input filter (e.g. {TextField} truncates to
-    #   fit `rect.width - 1`).
-    # - {#preprocess_paste} — the same for {#handle_paste}, which lands a
-    #   whole clipboard at the caret in one mutation.
+    # - {#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=},
+    #   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
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
@@ -56,7 +88,6 @@ module Tuile
         @caret = 0
         @on_change = nil
         @on_value_change = nil
-        @on_key = nil
         @on_escape = method(:default_on_escape)
       end
 
@@ -89,20 +120,6 @@ module Tuile
       # @return [Proc, Method, nil] one-arg callable, or nil.
       attr_accessor :on_change
 
-      # Optional interceptor consulted before the input's own key handling.
-      # Receives the pressed key; return a truthy value to consume it (the
-      # input then ignores that key), falsy to let normal editing proceed.
-      #
-      # The keyboard analog of {#on_change}: it lets app code layer behavior
-      # onto an input without subclassing. The motivating case is an
-      # autocomplete / slash-command overlay (a non-modal {Component::Popup}):
-      # while it is open the interceptor claims Up/Down/Enter/ESC and forwards
-      # them to the overlay's list, but lets ordinary characters fall through
-      # so typing keeps editing the field (and {#on_change} keeps refilling the
-      # list).
-      # @return [Proc, Method, nil] one-arg callable, or nil.
-      attr_accessor :on_key
-
       # 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
@@ -144,25 +161,20 @@ module Tuile
         invalidate
       end
 
-      # Handles a key. An {#on_key} interceptor (if set) gets first refusal —
-      # a truthy return consumes the key — otherwise it delegates to
-      # {#handle_text_input_key}. Dispatch ({ScreenPane#handle_key}) only routes
-      # keys here when this input is on the focus chain, so there is no
-      # {#active?} gate.
+      # 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)
-        return true if @on_key&.call(key)
-
-        handle_text_input_key(key)
-      end
+      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.
       # {#preprocess_paste} filters it first.
       # @param text [String]
-      # @return [Boolean] always true — a field consumes every paste, an empty
-      #   one included.
+      # @return [Boolean] always true — a field consumes every paste: an empty
+      #   one, and one its {#insert_text} rejects wholesale.
       def handle_paste(text)
         insert_text(preprocess_paste(text))
         true
@@ -180,8 +192,28 @@ module Tuile
       # @return [String]
       def preprocess_paste(text) = text.tr("\t", " ").gsub(/[\x00-\x09\x0b-\x1f\x7f]/, "")
 
-      # Inserts `str` at the caret, leaving the caret behind it. The bulk
-      # counterpart of a subclass's per-key insert.
+      # Inserts `str` at the caret, leaving the caret behind it.
+      #
+      # **Every insertion lands here** — a typed character, the ENTER newline
+      # and a whole pasted clipboard alike — so a field constrains its contents
+      # by overriding this, and one override covers typing and pasting both:
+      #
+      #   def insert_text(str)      # hex digits only, in a TextField subclass
+      #     return false unless @text.dup.insert(@caret, str).match?(/\A\h*\z/)
+      #
+      #     super
+      #   end
+      #
+      # Test the whole resulting buffer, as above, and not the fragment being
+      # inserted: sieving per character turns a pasted `"1,5"` into the
+      # plausible, wrong `"15"`, where an all-or-nothing test drops it — which
+      # is also what typing the comma does. Filtering at all works only for a
+      # grammar every valid value can be *typed through*; one where it can't
+      # (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.
       # @param str [String]
       # @return [Boolean] true if the text changed.
       def insert_text(str)
@@ -193,20 +225,25 @@ module Tuile
         true
       end
 
-      # Renders `text` on the field's background well, looked up from the
-      # current {Screen#theme} at paint time: {Theme#active_bg_color} when this
-      # input is on the active (focus) chain, {Theme#input_bg_color} otherwise —
-      # visibly a field either way, distinctly highlighted when active.
-      # @param text [String]
-      # @return [StyledString] text on the field's background well.
-      def background(text)
-        StyledString.styled(text, bg: active? ? screen.theme.active_bg_color : screen.theme.input_bg_color)
-      end
-
-      # Input filter for {#text=}. Subclasses override to truncate or reject
-      # invalid input. Default coerces to String.
+      # 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
+      # today; a subclass that does is filtering the *programmatic* setter, not
+      # user input — that is {#insert_text}.
       # @param new_text [String]
-      # @return [String] possibly transformed text.
+      # @return [String] possibly transformed text; the default coerces to String.
       def preprocess_text(new_text) = new_text.to_s
 
       # The one measurement primitive both inputs share: a caret index counts
@@ -230,13 +267,14 @@ module Tuile
       # @return [void]
       def on_caret_mutated; end
 
-      # Dispatch hook for {#handle_key}. Handles ESC and the navigation keys
-      # that have identical semantics in single-line and multi-line inputs:
+      # 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. Subclasses
-      # override to add their own keys (HOME/END, UP/DOWN, ENTER, BACKSPACE/
-      # DELETE, printable insertion) and call `super` to fall back to the
-      # common navigation handling.
+      # moves), CTRL+LEFT/CTRL+RIGHT for word jumps, and CTRL+W, which deletes
+      # exactly what CTRL+LEFT would have skipped over (readline's
+      # `unix-word-rubout`). Subclasses override to add their own keys (HOME/END,
+      # UP/DOWN, ENTER, CTRL+U, BACKSPACE/DELETE, printable insertion) and call
+      # `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)
@@ -245,6 +283,7 @@ module Tuile
         when Keys::RIGHT_ARROW then self.caret = cluster_boundary_after(@caret)
         when Keys::CTRL_LEFT_ARROW then self.caret = word_left
         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?
 
@@ -259,10 +298,19 @@ module Tuile
       # glyph, whatever it is built from (a ZWJ emoji family and a three-jamo
       # Hangul syllable each go whole).
       # @return [void]
-      def delete_before_caret
-        return if @caret.zero?
+      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` is snapped forward onto a grapheme-cluster boundary, so a
+      # caller may compute it by counting characters.
+      # @param index [Integer] a {#text} index; clamped to `0..caret`.
+      # @return [void]
+      def delete_back_to(index)
+        start = snap_to_cluster(index.clamp(0, @caret))
+        return if start == @caret
 
-        start = cluster_boundary_before(@caret)
         new_text = @text.dup
         new_text.slice!(start...@caret)
         @caret = start

data/lib/tuile/component/abstract_wrapping_field.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # Abstract base for a field that **wraps one editor completely**: it carries
+    # a typed {HasValue#value} but paints nothing itself, handing the whole UI to
+    # a single {AbstractStringField} it owns and hides. Subclass it by passing
+    # the editor to `super` and defining the conversion both ways:
+    #
+    #   class IntegerField < Component::AbstractWrappingField
+    #     def initialize = super(TextField.new)
+    #
+    #     def value = Integer(editor.text, 10) rescue nil
+    #
+    #     def value=(new_value)
+    #       editor.text = new_value.nil? ? "" : new_value.to_s
+    #       editor.caret = editor.text.length
+    #     end
+    #
+    #     def empty_value = nil
+    #   end
+    #
+    # Everything else arrives already wired: the editor is added as the single
+    # child and positioned across {Component#rect}, focus forwards into it, it
+    # sits on this field's one background well, and {#placeholder} /
+    # {#on_enter} / {#cursor_position} / {#clear} are re-exposed here so an app
+    # never addresses it. Give the field a single-row rect.
+    #
+    # == The editor is private machinery
+    # There is no public accessor — {#editor} is protected, for subclasses — and
+    # that is the point: swapping it would break the conversion. **An app never
+    # addresses the editor**; what it needs is either already delegated here or
+    # earns a forwarder here. It is still in `children`, because the tree is
+    # reported honestly, but that is not an invitation.
+    #
+    # A **spec** is the exception, and it has a sanctioned path — driving the
+    # 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
+    #
+    # 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
+    # instead:
+    #
+    #   def initialize
+    #     super(TextField.new)
+    #     editor.max_text_length = 20   # an internal cap, not part of my surface
+    #   end
+    #
+    # == Committing: leaving the widget, and ENTER
+    # {#commit} fires on both commit gestures. Leaving the focus chain is one —
+    # the *field*'s, not its editor's, which is left on every hop within a
+    # widget. ENTER is the other, because a form whose default button is reached
+    # 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
+    #
+    # 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.
+    #
+    # == Implementation details
+    # - **{HasValue#value} and {#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.
+    # - **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
+    #   commit moves its value — which is the same line {HasBadInput} draws.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class AbstractWrappingField < Component
+      include HasValue
+      include HasPlaceholder
+
+      # @param editor [AbstractStringField] the editor to wrap; becomes this
+      #   field's single child and is never swapped.
+      # @raise [TypeError] unless `editor` is an {AbstractStringField}.
+      def initialize(editor)
+        super()
+        raise TypeError, "expected AbstractStringField, got #{editor.inspect}" unless editor.is_a?(AbstractStringField)
+
+        @editor = editor
+        @last_value = empty_value
+        @on_enter = nil
+        # 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
+        end
+        add_child(editor, at: 0)
+      end
+
+      # @return [Object] the typed value, parsed from the editor's buffer.
+      # @raise [NotImplementedError] unless the subclass overrides it.
+      def value = raise(NotImplementedError, "#{self.class} must implement value")
+
+      # Writes `new_value` into the editor's buffer.
+      # @param new_value [Object]
+      # @return [void]
+      # @raise [NotImplementedError] unless the subclass overrides it.
+      def value=(new_value)
+        raise(NotImplementedError, "#{self.class} must implement 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
+
+      # @return [String, nil] the hint the editor paints while empty
+      #   ({HasPlaceholder}).
+      def placeholder = editor.placeholder
+
+      # @param text [String, nil]
+      # @return [void]
+      # @raise [TypeError] unless `text` is a String or nil.
+      def placeholder=(text)
+        editor.placeholder = text
+      end
+
+      # @return [Proc, Method, nil] fired when ENTER is pressed, *after*
+      #   {#commit}; see {TextField#on_enter}.
+      attr_reader :on_enter
+
+      # @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
+      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
+      # 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
+        super
+      end
+
+      # @return [Point, nil] the editor's caret — the hardware cursor is
+      #   delegated to it.
+      def cursor_position = editor.cursor_position
+
+      # Runs {#commit} on the falling edge, i.e. when this field leaves the focus
+      # chain. Moving focus *within* a widget keeps it active, so a future
+      # multi-editor field inherits the same semantics unchanged.
+      # @param flag [Boolean]
+      # @return [void]
+      def active=(flag)
+        was = active?
+        super
+        commit if was && !active?
+      end
+
+      # @return [void]
+      def on_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.
+      attr_reader :editor
+
+      # Called on a commit gesture — the field leaving the focus chain, or
+      # ENTER; no-op by default. This is the commit point a canonicalizing
+      # field rewrites its buffer from.
+      # @return [void]
+      def commit = nil
+
+      # 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
+      # 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
+
+      # 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
+
+      private
+
+      # 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.
+      # @return [void]
+      def fire_if_changed
+        v = value
+        return if v == @last_value
+
+        @last_value = v
+        on_value_change&.call(v)
+      end
+    end
+  end
+end