tuile 0.15.0 → 0.16.0

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

data/lib/tuile/component/has_bad_input.rb

@@ -25,7 +25,7 @@ module Tuile
     #
     # == Implementation details
     # An includer overrides {#bad_input_message} and nothing else. Two rules
-    # bind that override, and `DECISIONS.md` `D_bad_input` has the why:
+    # bind that override, and `design/decisions.md` `D_bad_input` has the why:
     #
     # - **Empty input is not bad input.** Return `nil` for an empty buffer even
     #   though it parses to nothing, or every blank *optional* field blocks a
@@ -79,7 +79,7 @@ module Tuile
       #   def bad_input_settled? = @settled   # set on commit, cleared on an edit
       #
       # It gates the **ink only**: {#bad_input?} is a pull, and a save gate
-      # asking at a click must get the answer settled or not (`DECISIONS.md`
+      # asking at a click must get the answer settled or not (`design/decisions.md`
       # `D_bad_input`).
       # @return [Boolean]
       def bad_input_settled? = true

data/lib/tuile/component/has_content.rb

@@ -62,7 +62,7 @@ module Tuile
 
         old = self.content
         # Detached without notifying, and notified at the very end: the focus
-        # repair in on_child_removed cascades into whatever occupies the slot
+        # repair in handle_child_removed cascades into whatever occupies the slot
         # *now*, so it has to see the new content (window_spec pins it).
         detach_child(old) unless old.nil?
         @content = content
@@ -71,7 +71,7 @@ module Tuile
           content.invalidate
           layout(content)
         end
-        on_child_removed(old) unless old.nil?
+        handle_child_removed(old) unless old.nil?
       end
 
       # @param rect [Rect]
@@ -82,7 +82,7 @@ module Tuile
       end
 
       # @return [void]
-      def on_focus
+      def handle_focus
         super
         # Let the content component receive focus, so that it can immediately
         # start responding to key presses. Hidden content is left alone, so

data/lib/tuile/component/has_placeholder.rb

@@ -21,7 +21,7 @@ module Tuile
     # Include it in a field whose *input shape* is unguessable from an empty
     # well. Not in {Select}, the near miss: a blank face plus `▾` already reads
     # as "nothing picked", so an absent enum *value* needs no hint the way an
-    # unguessable input *format* does (`DECISIONS.md` `D_select`).
+    # unguessable input *format* does (`design/decisions.md` `D_select`).
     #
     # == Implementation details
     # The ink is {Theme#placeholder_color}, calibrated to be *barely* visible —

data/lib/tuile/component/has_validation.rb

@@ -30,7 +30,7 @@ module Tuile
     # nothing — where red *text* is invisible on the empty field that is the
     # required-field case, and invisible again on content carrying colors of its
     # own. It takes two tokens rather than one because a focused invalid field
-    # still has to look focused (`DECISIONS.md` `D_has_validation`).
+    # still has to look focused (`design/decisions.md` `D_has_validation`).
     #
     # The well reaches the whole widget with nothing forwarding it: a composed
     # field's inner face is marked {Component::BG_INHERIT} and a group's {List}
@@ -53,7 +53,7 @@ module Tuile
     #
     # Unlike `bad_input?`, this fact is *discrete* — asserted at a click or a
     # binder pass, not recomputed per keystroke — which is why it carries a
-    # change notice where `bad_input?` deliberately doesn't (`DECISIONS.md`
+    # change notice where `bad_input?` deliberately doesn't (`design/decisions.md`
     # `D_bad_input`, `D_has_validation`).
     module HasValidation
       # @return [Proc, Method, nil] one-arg callable fired with the new message

data/lib/tuile/component/has_value.rb

@@ -68,7 +68,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       # @return [Boolean]
       def focusable? = true

data/lib/tuile/component/label.rb

@@ -60,7 +60,7 @@ module Tuile
       protected
 
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         update_rows
       end

data/lib/tuile/component/layout/box.rb

@@ -190,7 +190,10 @@ module Tuile
         # {Component#visible=} buys over `remove` plus `add(…, at:)`.
         # @param _child [Component]
         # @return [void]
-        def on_child_visibility_changed(_child) = relayout
+        def handle_child_visibility_changed(_child)
+          super
+          relayout
+        end
 
         private
 

data/lib/tuile/component/layout.rb

@@ -173,7 +173,7 @@ module Tuile
       # the popup. Layouts don't paint any visible chrome of their own
       # (the auto-cleared background is just blank space), so this has no
       # mouse-routing consequences — clicks on a gap area land back on the
-      # Layout itself and the on_focus cascade forwards to a tab stop.
+      # Layout itself and the handle_focus cascade forwards to a tab stop.
       def focusable? = true
 
       # Adds a child component to this layout.
@@ -198,7 +198,7 @@ module Tuile
       end
 
       # @return [void]
-      def on_focus
+      def handle_focus
         super
         # Forward focus to the first interactive widget in the subtree so the
         # user can start typing / cursoring immediately. Prefer a {#tab_stop?}
@@ -210,7 +210,7 @@ module Tuile
         # Both halves skip hidden subtrees — this is the cascade that would
         # otherwise walk straight back into the pane just hidden.
         first_tab_stop = nil
-        on_shown_tree { |c| first_tab_stop ||= c if !c.equal?(self) && c.tab_stop? }
+        walk_shown_tree { |c| first_tab_stop ||= c if !c.equal?(self) && c.tab_stop? }
         if first_tab_stop
           screen.focused = first_tab_stop
         else

data/lib/tuile/component/list.rb

@@ -6,7 +6,7 @@ module Tuile
     #
     #   list = Component::List.new
     #   list.items    = people
-    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.hint(" #{p.email}") }
+    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.fg(:muted, " #{p.email}") }
     #   list.cursor   = List::Cursor.new                  # a bare list has none
     #   list.on_item_chosen = ->(index, person) { open(person) }
     #
@@ -249,7 +249,7 @@ module Tuile
 
       # @param key [String] a key.
       # @return [Boolean] true if the key was handled.
-      def handle_key(key)
+      def handle_key?(key)
         if key == Keys::PAGE_UP
           move_scroll_top_row_by(-viewport_rows)
           true
@@ -259,7 +259,7 @@ module Tuile
         elsif key == Keys::ENTER && cursor_on_item?
           fire_item_chosen
           true
-        elsif @cursor.handle_key(key, @items.size, viewport_rows)
+        elsif @cursor.handle_key?(key, @items.size, viewport_rows)
           move_viewport_to_cursor
           notify_cursor_changed
           invalidate
@@ -316,25 +316,35 @@ module Tuile
         true
       end
 
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        if event.button == :scroll_down
-          move_scroll_top_row_by(4)
-        elsif event.button == :scroll_up
-          move_scroll_top_row_by(-4)
-        else
-          return unless rect.contains?(event.point)
+      # Moves the cursor to the pressed row and fires {#on_item_chosen}; what
+      # each {Cursor} does with a press is its own.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
-          item_index = event.y - rect.top + scroll_top_row
-          if @cursor.handle_mouse(item_index, event, @items.size)
-            move_viewport_to_cursor
-            notify_cursor_changed
-            invalidate
-          end
-          fire_item_chosen if event.button == :left && item_index >= 0 && item_index < @items.size && cursor_on_item?
+        item_index = event.y - rect.top + scroll_top_row
+        if @cursor.handle_mouse_down?(item_index, event, @items.size)
+          move_viewport_to_cursor
+          notify_cursor_changed
+          invalidate
         end
+        fire_item_chosen if item_index >= 0 && item_index < @items.size && cursor_on_item?
+        true
+      end
+
+      # Scrolls four rows a notch, and declines — so the notch bubbles to an
+      # ancestor scroller — once this list is at that end of its items.
+      # @param event [Mouse::ScrollEvent]
+      # @return [Boolean]
+      def handle_mouse_scroll?(event)
+        before = scroll_top_row
+        case event.direction
+        when :down then move_scroll_top_row_by(4)
+        when :up   then move_scroll_top_row_by(-4)
+        else return false
+        end
+        scroll_top_row != before
       end
 
       # Paints the visible items into {#rect}, rendering the ones not already
@@ -379,15 +389,15 @@ module Tuile
           # @param _item_count [Integer]
           # @param _viewport_rows [Integer]
           # @return [Boolean]
-          def handle_key(_key, _item_count, _viewport_rows)
+          def handle_key?(_key, _item_count, _viewport_rows)
             false
           end
 
           # @param _item_index [Integer]
-          # @param _event [MouseEvent]
+          # @param _event [Mouse::DownEvent]
           # @param _item_count [Integer]
           # @return [Boolean]
-          def handle_mouse(_item_index, _event, _item_count)
+          def handle_mouse_down?(_item_index, _event, _item_count)
             false
           end
 
@@ -422,7 +432,7 @@ module Tuile
         # @param item_count [Integer] number of items in the list.
         # @param viewport_rows [Integer] number of visible rows.
         # @return [Boolean] true if the cursor moved.
-        def handle_key(key, item_count, viewport_rows)
+        def handle_key?(key, item_count, viewport_rows)
           case key
           when *Keys::DOWN_ARROWS
             go_down_by(1, item_count)
@@ -441,11 +451,11 @@ module Tuile
           end
         end
 
-        # @param item_index [Integer] the item the cursor is hovering over.
-        # @param event [MouseEvent] the event.
+        # @param item_index [Integer] the item pressed on.
+        # @param event [Mouse::DownEvent] the event.
         # @param item_count [Integer] number of items in the list.
-        # @return [Boolean] true if the event was handled.
-        def handle_mouse(item_index, event, item_count)
+        # @return [Boolean] true if the cursor moved.
+        def handle_mouse_down?(item_index, event, item_count)
           if event.button == :left
             go(item_index.clamp(nil, item_count - 1))
           else
@@ -507,10 +517,10 @@ module Tuile
           end
 
           # @param item_index [Integer]
-          # @param event [MouseEvent]
+          # @param event [Mouse::DownEvent]
           # @param _item_count [Integer]
           # @return [Boolean]
-          def handle_mouse(item_index, event, _item_count)
+          def handle_mouse_down?(item_index, event, _item_count)
             if event.button == :left
               prev_pos = @positions.reverse_each.find { _1 <= item_index }
               return go_to_first if prev_pos.nil?
@@ -571,7 +581,7 @@ module Tuile
       # was skipped because there was no viewport — re-run it now that there
       # is one, so the list snaps to the bottom on first paint.
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         drop_row_cache
         update_scroll_top_row_if_auto_scroll
@@ -738,7 +748,7 @@ module Tuile
       # negating the auto-scroll. Skipped when {#rect} is empty: without a
       # viewport the "items minus viewport" formula yields `@items.size`,
       # which would leave `scroll_top_row` past the last item once a real rect
-      # arrives. {#on_width_changed} re-runs this hook when the rect grows so
+      # arrives. {#handle_width_changed} re-runs this hook when the rect grows so
       # the snap-to-bottom intent is preserved.
       #
       # Gated on {#following?}: once the user scrolls up off the bottom the

data/lib/tuile/component/list_dropdown.rb

@@ -195,7 +195,7 @@ module Tuile
       # @param width [Integer] the panel's width in columns, clamped to the
       #   screen. **Required, with no default:** `anchor.width` is the *parent's*
       #   width and would be meaningless here, so the caller measures (see
-      #   `DECISIONS.md` `D_select` on why the width policy stays with the
+      #   `design/decisions.md` `D_select` on why the width policy stays with the
       #   driver).
       # @param max_rows [Integer] rows shown before the list scrolls.
       # @return [void]
@@ -244,7 +244,7 @@ module Tuile
       def move(key)
         return false unless open? && MOVE_KEYS.include?(key)
 
-        @list.handle_key(key)
+        @list.handle_key?(key)
         true
       end
 
@@ -253,7 +253,7 @@ module Tuile
       # own Enter branch.
       # @return [Boolean] true iff a row was chosen (false when the cursor is
       #   off-content).
-      def choose = @list.handle_key(Keys::ENTER)
+      def choose = @list.handle_key?(Keys::ENTER)
     end
   end
 end

data/lib/tuile/component/menu_bar/cascade.rb

@@ -8,18 +8,18 @@ module Tuile
       # machinery of {MenuBar}; an app never names it.
       #
       #   cascade.open_below(segment_rect, item)   # Enter/Down on the strip
-      #   return true if cascade.handle_key(key)   # MenuBar#handle_key, first
+      #   return true if cascade.handle_key?(key)   # MenuBar#handle_key?, first
       #   cascade.close                            # focus lost, or rect changed
       #
       # A panel is a **non-modal overlay, not a child**, so it never takes focus:
       # focus stays on the {MenuBar} for the whole interaction and every key
-      # arrives via {MenuBar#handle_key}, which offers it here first. That is
+      # arrives via {MenuBar#handle_key?}, which offers it here first. That is
       # {Component::Select}'s architecture extended to N levels, and it is why
       # nothing in the key-dispatch ladder changes.
       #
       # Widths are measured here, per level — the panel is as wide as the level's
       # widest label — because {ListDropdown} deliberately measures nothing
-      # itself (`DECISIONS.md` `D_select`).
+      # itself (`design/decisions.md` `D_select`).
       #
       # == Implementation details
       # While open it consumes **everything** except the two keys that mean
@@ -73,7 +73,7 @@ module Tuile
         # @return [Boolean] `true` when consumed — almost always, while open.
         #   `false` when closed, and for the two sideways keys {MenuBar} answers
         #   (see the class docs).
-        def handle_key(key)
+        def handle_key?(key)
           return false unless open?
           return true if deepest.move(key)
 
@@ -105,7 +105,7 @@ module Tuile
         # @param key [String] a single printable, already downcased.
         # @return [Boolean] whether an item on the deepest level claimed it. A
         #   miss is never offered to a shallower level.
-        def handle_mnemonic(key)
+        def handle_mnemonic?(key)
           return false unless open?
 
           level = depth - 1