tuile 0.14.0 → 0.16.0

data/lib/tuile/component/date_field.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A single-line field whose {#value} is a stdlib `Date` (or `nil` when
+    # 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.value = Date.new(2026, 9, 4)                # field shows "2026-09-04"
+    #   field.placeholder                                 # => "yyyy-mm-dd"
+    #   field.clear                                       # empties it; value => nil
+    #
+    # Up/Down step a day (an empty field steps to today), and the hint an empty
+    # field paints is derived from the format — set {#placeholder} to override
+    # it, or `""` to suppress it.
+    #
+    # == Several formats in, one format out
+    # {#formats} is a list of strftime patterns. Parsing tries them in order and
+    # the first match wins, while `formats.first` — *the primary* — is what
+    # {#value=} writes and what a loosely typed buffer is rewritten into once
+    # the user leaves the field or presses ENTER. So it is lenient about what it
+    # accepts and strict about what it shows, and the list is the leniency knob:
+    #
+    #   field.formats = ["%d.%m.%Y", "%Y-%m-%d"]
+    #   # the user types "2026-9-4" and Tabs away; the field shows "04.09.2026"
+    #
+    # **The order is the disambiguation, and it is the app's call**: `"%m/%d/%Y"`
+    # and `"%d/%m/%Y"` both match `04/09/2026` and disagree about what it means,
+    # which no validation can detect — a wrong value that saves cleanly is worse
+    # than input the user can see is bad. An app setting a list owns that call;
+    # the *detected* list invents nothing, carrying what the system said (with a
+    # two-digit year widened) and ISO behind it.
+    #
+    # == The conventions come from the session, unless you say otherwise
+    # {#formats} and {#calendar_start} follow {Screen#locale} until they are
+    # assigned, so a stock field spells dates the way the user's environment
+    # says to, and an app wanting one spelling everywhere sets it once:
+    #
+    #   screen.locale = Locale::ISO.with(date_formats: ["%d.%m.%Y"])  # session-wide
+    #   field.formats = "%d.%m.%Y"                                    # this field only
+    #   field.formats = nil                                           # follow again
+    #
+    # A mid-session {Screen#locale=} reaches an inheriting field: the hint is
+    # re-derived, and a buffer that still parses is rewritten in the new primary
+    # format. One that no longer parses is left exactly as typed and reads as
+    # bad input.
+    #
+    # == Input the field cannot parse is *reported*, not filtered
+    # A date's grammar is not prefix-closed (`"2020-13-45"` is well-formed at
+    # every character), so nothing is filtered: every character is admitted,
+    # typed or pasted, and the residue is reported through {HasBadInput}. A form
+    # asks {HasBadInput#bad_input?} *before* {HasValue#empty?}, since a field
+    # full of garbage reads `nil`:
+    #
+    #   field.value          # => nil
+    #   field.empty?         # => true  — empty of *value*
+    #   field.bad_input?     # => true
+    #
+    # The red **well**, unlike that report, waits for a commit gesture: since
+    # every prefix of a date is bad input, painting it per keystroke would hold
+    # the field red for the whole time the user types a correct one. So `2`,
+    # `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
+    #   value with no edit, and a buffer the field cannot parse is left exactly
+    #   as typed, because the user has to see what they wrote in order to fix it.
+    # - **Canonicalizing fires no {HasValue#on_value_change}** — the spelling
+    #   changed, not the value. Up/Down canonicalize too, since they go through
+    #   {#value=}, so Up-then-Down does not restore the text you typed.
+    # - **The calendar is proleptic Gregorian, not Ruby's `Date::ITALY`**, which
+    #   matters for dates near and before the 1582 reform: {#calendar_start}.
+    # - **A format is checked when it is assigned**, not at the first keystroke:
+    #   {#formats=}.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class DateField < AbstractWrappingField
+      include HasBadInput
+
+      # @return [String] what {HasBadInput#bad_input_message} reports for a
+      #   buffer no configured format parses.
+      BAD_INPUT_MESSAGE = "not a valid date"
+      private_constant :BAD_INPUT_MESSAGE
+
+      # No format renders a date past ~30 columns ("Wednesday, 04 September
+      # 2026"), so this caps nothing an app configured — it stops a pasted
+      # novel from sitting in the buffer.
+      # @return [Integer]
+      MAX_TEXT_LENGTH = 64
+      private_constant :MAX_TEXT_LENGTH
+
+      def initialize
+        super(TextField.new)
+        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) }
+        @settled = false
+        @placeholder_override = nil
+        # Both nil: follow the screen's locale until an app overrides them.
+        @formats = nil
+        @calendar_start = nil
+        sync_placeholder
+      end
+
+      # @return [Date, nil] the buffer parsed by the first format that matches
+      #   it whole; `nil` when the buffer is empty or no format parses it.
+      def value
+        text = editor.text
+        return nil if text.empty?
+
+        formats.each do |format|
+          date = parse(text, format)
+          return date unless date.nil?
+        end
+        nil
+      end
+
+      # Writes `new_value` into the buffer in the primary format and parks the
+      # caret at its end; fires {HasValue#on_value_change} only if the value
+      # actually changed.
+      #
+      # Thin and lenient, deliberately: anything answering `strftime` is taken
+      # and truncated to its civil date, the same lenient-in/strict-out shape as
+      # the format list itself.
+      #
+      #   field.value = Time.now   # shows today; reads back a Date, time dropped
+      #
+      # @param new_value [Date, nil] `nil` empties the field.
+      # @return [void]
+      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.
+      # @return [nil]
+      def empty_value = nil
+
+      # The accepted formats, primary first — this field's own if one was set,
+      # otherwise the screen's ({Locale#date_formats}), which is what makes a
+      # stock field follow the session's conventions with no configuration.
+      # Frozen either way: assign a new list rather than pushing onto this one,
+      # or the validator and the derived {#placeholder} are both bypassed.
+      # @return [Array<String>]
+      def formats = @formats || locale.date_formats
+
+      # Sets the formats, re-derives the {#placeholder}, and fires
+      # {HasValue#on_value_change} if the buffer now parses differently.
+      #
+      #   field.formats = "%d.%m.%Y"                 # the one-format shorthand
+      #   field.formats = ["%d.%m.%Y", "%Y-%m-%d"]   # lenient in, first one out
+      #   field.formats = nil                        # back to following the locale
+      #
+      # Only the primary must round-trip; every later entry only ever parses,
+      # which is what lets a lenient list carry a two-digit-year pattern behind
+      # a widened one ({Locale::DateFormats.validate}).
+      #
+      # A non-empty buffer is left alone: it is text, and it reparses under the
+      # new list on the next read.
+      # @param list [String, Array<String>, nil] one format, several, or `nil`
+      #   to inherit {Screen#locale} again.
+      # @return [void]
+      # @raise [TypeError] on anything but a String, an Array of Strings or nil.
+      # @raise [ArgumentError] on an empty list, `%x`/`%X`/`%c`, a primary that
+      #   does not survive a `strftime`/`strptime` round-trip — notably one
+      #   carrying `%y`, which cannot carry a century — or any entry `strptime`
+      #   cannot use.
+      def formats=(list)
+        @formats = list.nil? ? nil : Locale::DateFormats.validate(list)
+        sync_placeholder
+        fire_if_changed
+      end
+
+      # When the Gregorian calendar takes over from the Julian one, as a Julian
+      # Day Number — `Date::GREGORIAN` (proleptic Gregorian) by default, *not*
+      # Ruby's `Date::ITALY`. That makes `1582-10-10` an ordinary date instead
+      # of a hole the user cannot type their way out of, and makes ISO output
+      # mean the ISO 8601 date, which mandates proleptic Gregorian.
+      #
+      # The cost, since it is real: the round-trip is exact only while the
+      # field's calendar matches that of the `Date`s the app hands it, and
+      # `Date.new(1500, 1, 1)` in app code is `ITALY`. So a pre-1582 date set
+      # that way comes back nine days off once the field canonicalizes the
+      # buffer. Set this to `Date::ITALY` if that is the app's world — or set it
+      # once for the whole session, since it is a {Locale} member that this
+      # reader falls back to:
+      # `screen.locale = Locale::ISO.with(calendar_start: Date::ITALY)`.
+      # @return [Numeric]
+      def calendar_start = @calendar_start || locale.calendar_start
+
+      # Sets the calendar and fires {HasValue#on_value_change} if the buffer now
+      # parses to a different date; the buffer itself is left alone.
+      # @param start [Numeric, nil] a Julian Day Number, one of `Date::ITALY` /
+      #   `Date::ENGLAND` / `Date::GREGORIAN` / `Date::JULIAN`, or `nil` to
+      #   inherit {Screen#locale} again.
+      # @return [void]
+      # @raise [TypeError] unless `start` is Numeric or nil.
+      def calendar_start=(start)
+        unless start.nil? || start.is_a?(Numeric)
+          raise TypeError, "expected a Numeric day of calendar reform or nil, got #{start.inspect}"
+        end
+
+        @calendar_start = start
+        fire_if_changed
+      end
+
+      # Overrides the hint derived from the primary format.
+      #
+      #   field.placeholder = "when it happened"   # a hint of your own
+      #   field.placeholder = ""                   # no hint at all
+      #   field.placeholder = nil                  # back to the derived one
+      #
+      # @param text [String, nil] `nil` restores the derived hint, `""`
+      #   suppresses it.
+      # @return [void]
+      # @raise [TypeError] unless `text` is a String or nil.
+      def placeholder=(text)
+        # The editor validates the type, so a bad one raises before it is stored.
+        editor.placeholder = text || derived_placeholder
+        @placeholder_override = text
+      end
+
+      # Nothing a format parses is bad input, and an *empty* buffer is empty
+      # rather than bad ({HasBadInput}) — so this reports the residue of a
+      # grammar that cannot be filtered as it is typed: every prefix of a date,
+      # and everything that is simply not one.
+      # @return [String, nil]
+      def bad_input_message = value.nil? && !editor.text.empty? ? BAD_INPUT_MESSAGE : nil
+
+      protected
+
+      # Rewrites a buffer that parses in the primary format, leaving one that
+      # does not exactly as the user typed it — and settles the field either
+      # way, so input it could not parse starts painting the well.
+      # @return [void]
+      def commit
+        date = value
+        self.value = date unless date.nil? # …which unsettles, hence the order
+        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
+      # 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
+        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 handle_locale_changed
+        super
+        # Both overridden: this field follows no session convention.
+        return if @formats && @calendar_start
+
+        sync_placeholder
+        date = value
+        self.value = date unless date.nil?
+        fire_if_changed # for the buffer that just *stopped* parsing: nothing above touched it
+      end
+
+      private
+
+      # @param flag [Boolean]
+      # @return [void]
+      def settle(flag)
+        return if @settled == flag
+
+        @settled = flag
+        # Nothing else painted: an ENTER on an untouched buffer writes no cells,
+        # and neither does leaving the field with bad input in it.
+        invalidate
+      end
+
+      # @param text [String]
+      # @param format [String]
+      # @return [Date, nil] `nil` unless `format` consumes `text` whole *and*
+      #   the fields it yields are a real date — `Date._strptime` checks
+      #   neither, happily ignoring a trailing `"junk"` and accepting
+      #   February 30th.
+      def parse(text, format)
+        parsed = Date._strptime(text, format)
+        return nil if parsed.nil? || !parsed[:leftover].to_s.empty?
+
+        Date.strptime(text, format, calendar_start)
+      rescue ArgumentError # Date::Error is one
+        nil
+      end
+
+      # Steps {#value} by `delta` days; an empty or unparseable field steps to
+      # today, which is what a calendar would have opened on.
+      # @param delta [Integer]
+      # @return [void]
+      def step(delta)
+        date = value
+        self.value = date.nil? ? Date.today : date + delta
+      end
+
+      # @return [void]
+      def sync_placeholder
+        editor.placeholder = @placeholder_override || derived_placeholder
+      end
+
+      # @return [String, nil] the hint for the primary format, or `nil` when it
+      #   holds a directive the humanizer cannot translate exactly — never a
+      #   half-translated one.
+      def derived_placeholder = Locale::DateFormats.humanize(formats.first)
+    end
+  end
+end

data/lib/tuile/component/date_time_field.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A one-row field pairing a {DateField} and a {TimeField} behind a single
+    # `DateTime`. Give it a single-row {#rect}, 16 columns or wider:
+    #
+    #   [2026-09-14] [13:45]
+    #               ↑ 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.value = DateTime.new(2026, 9, 14, 13, 45)      # "2026-09-14" / "13:45"
+    #   f.clear                                          # empties both halves
+    #
+    # Neither half is labelled: each paints the hint derived from its own format
+    # (`yyyy-mm-dd`, `hh:mm`), which names it while it is empty — the moment
+    # naming matters. The *caption* ("Starts at") belongs to the layout around
+    # the field, as it does for every field (`design/decisions.md`
+    # `D_caption_ownership`).
+    #
+    # == Tune the halves; don't replace them
+    # They are exposed read-only, so everything they configure is reached
+    # directly rather than forwarded through a second set of names:
+    #
+    #   f.date_field.formats = "%d.%m.%Y"   # ambiguous if it were `f.formats=`
+    #   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).
+    #
+    # == The value is a `DateTime` at +00:00
+    # Both halves feed it with no adapter, and the offset is a placeholder
+    # rather than a zone — {TimeField}'s epoch cost, taken the same way: a value
+    # that is visibly wrong where an instant was meant beats one that is subtly
+    # wrong. Combine it with a zone at your own boundary (`f.value&.to_time`).
+    #
+    # Lenient in, strict out, so an input carrying more than the halves can hold
+    # does not round-trip:
+    #
+    #   f.value = Time.now      # takes today's date and the wall clock
+    #   f.value == DateTime.now # => false — the zone went, and the seconds with it
+    #
+    # == Three states, and only one of them is this field's own fault
+    # {HasValue#value} is non-nil **iff both halves parse**, so a half going bad
+    # nils the whole value ({HasBadInput}: a field holds bad input *or* a value,
+    # never both). Who reddens follows from whether the fault is attributable:
+    #
+    #   date half     time half   value       bad_input?                       red
+    #   2026-09-14    13:45       DateTime    no                               nobody
+    #   (empty)       (empty)     nil         no — empty is not bad input      nobody
+    #   2026-99-99    13:45       nil         "not a valid date"               the date half
+    #   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
+    # 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.
+    #
+    # The one cost: **ENTER does not redden this field**, where it reddens a
+    # half. A save gate on ENTER over a date with no time still reads
+    # {HasBadInput#bad_input?} true and gets the message; only the ink waits for
+    # the blur.
+    #
+    # == 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
+    #   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`
+    #   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}
+    #   blanks it in the ambient background, so the two wells read as two fields
+    #   rather than one long one and each half keeps its own focus highlight.
+    # - **A half announces from its own `value=` and its Up/Down step** — the
+    #   other half of {AbstractWrappingField#notify_on_edit?}'s contract — so
+    #   writing a value into both halves would announce a half-assembled
+    #   `DateTime`. Suppressed while applying, and announced once from this
+    #   field's own diff.
+    # - **Nothing else is wired.** Focus forwards through {Layout#handle_focus},
+    #   the mouse routes down through {Mouse::Router}, each half commits
+    #   on its own blur (Tab between them canonicalizes the date and leaves this
+    #   field active), and ENTER commits inside the half and keeps bubbling to
+    #   the scope's default button.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class DateTimeField < Layout::Horizontal
+      include HasValue
+      include HasBadInput
+
+      # @return [String] what {HasBadInput#bad_input_message} reports when one
+      #   half holds a value and the other is empty.
+      HALF_FILLED_MESSAGE = "needs both a date and a time"
+      private_constant :HALF_FILLED_MESSAGE
+
+      # What {#value=} needs off whatever it is handed — the two halves' own
+      # leniencies, checked together so a rejected value writes neither.
+      # @return [Array<Symbol>]
+      CIVIL_PARTS = %i[strftime hour min sec].freeze
+      private_constant :CIVIL_PARTS
+
+      # The content ratio, which decides this field's minimum width rather than
+      # merely its looks: `2026-09-14` is 10 columns and `13:45` is 5, so at 16
+      # the 2:1 split lands exactly 10 / 5. A constant rather than a measurement,
+      # so a locale spelling dates longer simply reaches its own minimum later
+      # (`design/decisions.md` `D_date_time_field`).
+      # @return [Integer]
+      DATE_WEIGHT = 2
+      private_constant :DATE_WEIGHT
+
+      # @return [Integer]
+      TIME_WEIGHT = 1
+      private_constant :TIME_WEIGHT
+
+      def initialize
+        super(spacing: 1)
+        @date_field = DateField.new
+        @time_field = TimeField.new
+        @last_value = empty_value
+        @applying = false
+        # cross: Fixed[1] is load-bearing — neither half declares an extent, so
+        # 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 } }
+      end
+
+      # @return [DateField] the left half; tune it, never replace it.
+      attr_reader :date_field
+
+      # @return [TimeField] the right half; tune it, never replace it.
+      attr_reader :time_field
+
+      # @return [DateTime, nil] the two halves assembled, on the calendar
+      #   {DateField#calendar_start} parsed the date in; `nil` unless both parse.
+      def value
+        date = date_field.value
+        time = time_field.value
+        return nil if date.nil? || time.nil?
+
+        DateTime.new(date.year, date.month, date.day, time.hour, time.min, time.sec, 0, date.start)
+      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.
+      #
+      # @param new_value [DateTime, Time, nil] anything carrying both a civil
+      #   date and a time of day; `nil` empties both halves.
+      # @return [void]
+      # @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)
+        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}"
+        end
+
+        applying do
+          date_field.value = new_value
+          time_field.value = new_value
+        end
+        fire_if_changed
+      end
+
+      # `nil`, not a pair of nils: a field with no parseable date *and* time is
+      # empty.
+      # @return [nil]
+      def empty_value = nil
+
+      # Empties the *input* of both halves, not just the value — either may be
+      # holding glyphs no parse could use ({HasBadInput}).
+      # @return [void]
+      def clear
+        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
+      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
+        return attributed unless attributed.nil?
+
+        date_field.empty? ^ time_field.empty? ? HALF_FILLED_MESSAGE : nil
+      end
+
+      # Sets the verdict and syncs the halves' wells onto it.
+      # @param new_message [String, StyledString, nil]
+      # @return [void]
+      def error_message=(new_message)
+        super
+        sync_half_wells
+      end
+
+      # Syncs the halves' wells on both focus edges — this field inks its
+      # half-filled fault only once you have left it.
+      # @param flag [Boolean]
+      # @return [void]
+      def active=(flag)
+        was = active?
+        super
+        sync_half_wells unless was == active?
+      end
+
+      # @return [Size] the full width, one row — so a taller rect gets the
+      #   ambient background rather than this field's well ({Component#extent}).
+      def extent = Size.new(rect.width, 1)
+
+      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.
+      # @return [Boolean]
+      def bad_input_settled? = !attributable? && !active?
+
+      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?
+
+      # One idempotent sync over one condition, this field the sole writer of
+      # its halves' {Component#bg_color} — the shape a hook-owned resource takes.
+      # Called from the three places {HasValidation#error_ink?} can change: a
+      # verdict, a focus edge, and a half's announcement. Leave one out and this
+      # field stops inking while its halves stay marked, i.e. both halves flat
+      # with their wells gone.
+      # @return [void]
+      def sync_half_wells
+        ink = error_ink?
+        [date_field, time_field].each { _1.bg_color = ink ? BG_INHERIT : nil }
+      end
+
+      # @return [void]
+      def handle_half_change
+        sync_half_wells
+        fire_if_changed unless @applying
+      end
+
+      # Runs `block` with the halves' notices suppressed, so a value written
+      # into both is announced once rather than half-assembled.
+      # @return [void]
+      def applying
+        @applying = true
+        yield
+      ensure
+        @applying = false
+      end
+
+      # @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