tuile 0.10.0 → 0.11.0

data/ideas/arrow-key-navigation.md

@@ -0,0 +1,205 @@
+# Arrow keys move focus between fields — as a *behavior*, not a layout class
+
+**Status:** design sketch, 2026-08-12. Nothing built. Started from the
+sampler's PasswordField pane ("Up/Down between the three fields would be
+friendlier"), but that pane is a *demo* of the feature, not an argument for
+it — the argument is a ten-field form. Open questions at the bottom are the
+point of this file.
+
+## What is being proposed
+
+In a form, Up/Down moves focus between fields, in addition to Tab/Shift+Tab.
+Tab keeps its current job (cycle every tab stop in the scope, wrapping);
+arrows do *local* motion within one container and stop at its edges.
+
+## Why it's plausible at all: Tuile already has the whole mechanism
+
+Two findings from the survey, both load-bearing:
+
+1. **`TextField` already declines Up/Down by design.** `text_field.rb:134-140`:
+   `on_key_up` / `on_key_down` are nil by default and the nil branch is
+   `return false`, with rdoc reading "when nil, UP falls through to the parent
+   (default behavior)". The clash we feared was already resolved in the
+   direction that enables this.
+2. **Rung 3 of the key ladder is exactly the right hook.** `bubble_key` asks
+   the focused widget, then each ancestor. AGENTS.md already names this as the
+   sanctioned home for scope-wide keys ("a layout's one-key jumps to its
+   panes"). So this is a `handle_key` on a container — no dispatch phase, no
+   gate in `Screen#handle_key`, no framework change.
+
+   Worth stating explicitly for a future reader: the key ladder's "no gate, no
+   predicate, no mode flag" rule constrains `Screen#handle_key`, **not** a
+   component's own `handle_key`. Adding behavior at rung 3 is sanctioned; a
+   per-instance switch on a *component* is not the thing that rule forbids.
+
+Everything that must keep the arrows already claims them and wins for free:
+`TextArea`, `TextView`, `List`, the three numeric fields, `ComboBox`.
+
+## Prior art
+
+Splits by lineage, not by age:
+
+- **FTXUI** — closest to Tuile architecturally, and does exactly this.
+  `Container::Vertical` is *defined* as "navigated vertically using up/down
+  arrow keys"; `Container::Horizontal` gets left/right. Dispatch is our shape:
+  active child asked first, container only sees what the child declined
+  (`container.cpp`, `OnEvent`). Arrows do **not** wrap (`MoveSelector`); Tab
+  wraps (`MoveSelectorWrap`).
+- **Midnight Commander** — "to move between the widgets use the arrow keys or
+  the Tab key". The ncurses form-dialog lineage generally (`dialog`, newt)
+  behaves this way; only MC was verified.
+- **Bubble Tea** — the canonical `examples/textinputs` cycles focus on
+  up/down/tab/shift+tab, but app-side; the framework has no focus model.
+- **Textual, ratatui, Ink, Vaadin** — no. Textual is the explicit web/ARIA
+  position: Tab between widgets, arrows only *within* a composite widget.
+
+## The shape: a behavior on a layout, not a `Layout::Form`
+
+`Layout::Form < Layout::Vertical` was the first sketch and is **rejected**.
+Reasons, in order of force:
+
+- **Vaadin's FormGroup precedent.** It coupled `Binder` to layouting and was
+  abandoned for it. `Form` here would couple a layout algorithm to a key
+  behavior — a smaller version of the same mistake.
+- **It breaks the moment the layout is insufficient.** A real form needs a
+  nested `Horizontal` row, or an `Absolute` for a capped-proportion split. Now
+  the behavior is attached to the *outer* class and the nested layouts are
+  arbitrary, so "does this container navigate?" stops being answerable from
+  the class. Policy carried by a class is inherited by every subclass and
+  unavailable to every non-subclass; policy carried by a setter is per
+  instance and never inherited.
+- **COP says so.** `Layout::Vertical` is a *generic, domain-agnostic*
+  component, and the skill's rule for those is to externalize policy via
+  injected strategies — not to subclass per policy. A `Form` whose only
+  divergence is one `handle_key` is precisely the "shallow divergent
+  scaffolding — duplicate or inject, don't fold into a base" case.
+
+So: **any layout can be given the behavior; none has it by default.** virtui
+gets nothing and stays exactly as it is; a form opts in. The sampler's `form`
+helper (`sampler.rb:832`) becomes the one place the demo opts in.
+
+Concretely, the nesting story this buys — and it is the whole reason for the
+shape: a layout without the behavior **declines** the arrow key, so it bubbles
+to the next ancestor that *does* have it. An inner `Absolute` inside a
+navigating `Vertical` is therefore one opaque slot: focus anywhere inside it,
+Down moves to the next slot of the outer box. No inheritance, no surprise, and
+the answer is the same at any nesting depth.
+
+## Semantics that already look settled
+
+Recorded here so the open questions below stay narrow.
+
+- **Walk direct children, not `on_tree`.** A `Horizontal` row nested in a
+  navigating `Vertical`: flattened pre-order would make Down from the row's
+  left field jump to the row's *right* field, which is geometrically wrong.
+  Direct children makes Down go to the next row. (FTXUI indexes `children()`
+  for the same reason.) "Which direct child holds focus" is a parent-chain
+  walk from `screen.focused`, so depth doesn't matter.
+- **Skip children with no focusable descendant** (a `Label`, a spacer).
+- **Don't wrap; decline at the edge.** Two payoffs: nesting composes (an inner
+  box at its edge declines and the outer box moves to the next sibling group),
+  and wrapping stays Tab's distinguishing job. Same split FTXUI landed on.
+- **Descend via the existing focus cascade** — set `screen.focused` to the
+  sibling and let `Layout#on_focus` (`layout.rb:203`) forward to its first tab
+  stop. See open question on backwards entry.
+- **Mouse is untouched.** Popups are untouched — the bubble is already scoped
+  to the topmost modal popup.
+
+## The honest argument against
+
+A *partially* live feature is worse than an absent one: if arrows navigate in
+80% of positions the user can't build a model. Inside a form the exception set
+is mostly coherent — `TextArea` / `TextView` / `List` swallow arrows, and
+they're the *tall* widgets, where a user already expects arrows to move
+*inside* the box. That reads as "arrows move within a tall widget, between
+short ones", which is learnable and is the story MC tells.
+
+The three numeric fields break that story and are the real problem (see Q6).
+
+## Open questions
+
+**Q1 — What exactly is the knob?** Candidates, roughly in order of how much
+API they add:
+
+  a. keyword + accessor on `Layout`: `navigation: :vertical` / `:horizontal` /
+     `:both` / `nil` (default `nil`).
+  b. a strategy *object*: `layout.navigation = Layout::ArrowNavigation.new(...)`,
+     leaving room for per-instance config and app subclassing.
+  c. a module the app mixes in: `Vertical.new.extend(Layout::ArrowNavigable)`.
+     Composable with any layout without touching `Layout`, but `extend` on a
+     singleton class is obscure and hard to document.
+  d. a general `Component#on_key` interceptor hook (the shape
+     `AbstractStringField#on_key` already has), with the framework shipping a
+     ready-made callable to assign. Most decoupled — touches `Layout` not at
+     all — but adds a general hook whose merits should be argued on their own,
+     not smuggled in under this feature.
+
+  (a) is the smallest thing that works; (d) is the most COP-pure. Not decided.
+
+**Q2 — Where does the axis come from?** If the behavior is layout-agnostic it
+can't be derived from the class. `Vertical` → up/down and `Horizontal` →
+left/right are natural defaults, but `Absolute` has none. Does the knob always
+carry an explicit axis, or default per class and require it on `Absolute`?
+
+**Q3 — Should `Horizontal` / left-right navigation exist at all?**
+`AbstractStringField` *always* consumes Left/Right for the caret, so a row of
+text fields will never arrow-navigate while a row of Buttons/Checkboxes will.
+The rule stays uniform (widget wins); the outcome looks selective. Ship both
+axes, or vertical-only until someone asks?
+
+**Q4 — Ordering inside an `Absolute`.** Declaration order is all that's
+available and may not match visual order — the original worry that killed the
+idea of putting this on every layout. Options: document "declaration order is
+yours to get right"; or sort direct children geometrically per keypress (by
+`rect.top`, then `rect.left`), which is cheap and actually correct, and would
+make `Absolute` a first-class citizen here. Is geometric ordering worth it?
+
+**Q5 — Backwards entry into a multi-widget sibling.** `Layout#on_focus` always
+forwards to the *first* tab stop, so arrowing **Up** into a previous group
+lands on its first widget rather than its last. FTXUI has the same wart. Fix
+with a `last:` variant of the cascade, or accept it?
+
+**Q6 — The numeric fields.** `IntegerField` / `FloatField` / `BigDecimalField`
+consume Up/Down to step by ±1, and they are *one row tall* — so they break the
+"arrows move within tall widgets" story silently, with nothing on screen
+explaining why. This is the sharpest concrete collision. Options:
+
+  a. leave it; document the exception,
+  b. move stepping to `Ctrl+Up/Down` or `PgUp/PgDn` (breaking, but the fields
+     are young),
+  c. make stepping opt-in per field (`step = 1` / `nil`) — a knob, but on the
+     widget that actually has the ambiguity, and a numeric field in a form
+     usually doesn't want spinner behavior anyway.
+
+**Q7 — `List` at its edges.** It clamps and returns true, so arrows can never
+escape a focused list; only Tab does. Keep clamping (a list is a list, and MC
+agrees), or have it decline at its edges so arrows escape? Note this is
+exactly virtui's shape, so the answer matters more there than in a form.
+
+**Q8 — `ComboBox` is asymmetric.** Closed, it eats Down to open the menu
+(`combo_box.rb:181`) but declines Up. So Up would jump out of a closed combo
+while Down opens it. Browsers eat both. Deliberate choice or accident to fix?
+
+**Q9 — Naming.** "Form" is the wrong word for the behavior — it's *focus
+navigation*. `navigation` / `arrow_nav` / `key_navigation` /
+`focus_navigation`? Whatever it is, it must not imply validation or submit,
+which Tuile has no notion of.
+
+**Q10 — Does Enter participate?** `dialog(1)` moves to the next field on
+Enter. Almost certainly out of scope — `Checkbox`, `Button` and `TextArea` all
+claim Enter already, and book ch5 has the per-widget Enter table — but worth
+rejecting explicitly rather than by omission.
+
+**Q11 — Where does the code live?** Zeitwerk wants one top-level constant per
+file. If Q1 lands on (b) or (c) it needs its own file under
+`lib/tuile/component/layout/`; if (a), it's a few lines on `Layout` itself.
+Also: any public signature change means `rake sig` in the same commit.
+
+## Graduation
+
+If built: the user-facing half goes to book ch5 (the key/Enter tables live
+there), the invariants half to AGENTS.md's key-dispatch section, and the
+choice-plus-rejected-roads half to `DECISIONS.md` as `D-arrow-navigation` —
+which must record the `Layout::Form` rejection and the Vaadin FormGroup
+precedent behind it, since that's the reasoning most likely to be
+re-litigated. Then retire this file.

data/ideas/new-components.md

@@ -15,6 +15,10 @@ built 2026-07-31; `progress-bar` (`D-color-slots`, book ch7 "Reporting
 progress") and `password-field` (`D-integer-field`'s taxonomy, book ch7
 "Editing text"), both built 2026-08-02.
 
+The **box layouts** that headed the gating list below are done too
+(`D-box-layouts`, 2026-08-07) — `Layout::Vertical` / `::Horizontal`, plus the
+sampler ported onto them.
+
 ## What Tuile already has
 
 Seven of the 54 have a counterpart: Button, Text Field, Text Area,
@@ -34,19 +38,19 @@ That leaves ~46 gaps.
 
 | Component | Builds on | Note |
 |---|---|---|
-| Box layouts (H/V) | `Layout` | Tuile has only `Layout::Absolute`. Biggest structural win; unblocks half of this table |
+| ~~Box layouts (H/V)~~ | `Layout` | **built** 2026-08-07 (`D-box-layouts`, book ch3); `Vertical`/`Horizontal` over `Box`, additive sugar on top of `Absolute` — no foundation change |
 | ~~Checkbox~~ | `HasValue` | **built** 2026-07-30 (`D-boolean-fields`); tri-state still deferred |
 | ~~Radio Group~~ | `List` + `HasValue` | **built** 2026-07-31 (`D-radio-group`); composes a `List`, cursor roams and Space selects |
 | ~~Checkbox Group~~ | `List` + `HasValue` | **built** 2026-07-30 (`D-checkbox-group`); composes a `List`, frozen `Set` value |
-| Select | `ComboBox` − filter | ComboBox with a read-only field; near-free. Deferred once already in `D-combobox` (wants the parked read-only axis) |
-| Password Field | `TextField` | masked repaint only |
-| Number Field | `IntegerField` twin | same composed-field shape, `Float` |
-| Progress Bar | `draw_line` + `EventQueue#tick_fps` | ticker for the indeterminate mode |
+| ~~Select~~ | `ListDropdown` + `HasValue` | **built** 2026-08-12 (`D-select`, book ch7); a *second driver* of `ListDropdown`, not "ComboBox − filter" — it paints its own one-row face and needs no read-only axis. Claims no printable but Space |
+| ~~Password Field~~ | `TextField` | **built** 2026-08-02 (`D-integer-field`'s taxonomy — subclass, since a password's value *is* its text; mask default in `D-ambiguous-width`); a `display_text` seam, one mask glyph per character |
+| ~~Number Field~~ | `IntegerField` twin | **built** 2026-08-07 as `FloatField` (`D-float-field`) and `BigDecimalField` (`D-bigdecimal-field`, on Tuile's first optional dep); each named for its Ruby value type, deliberate copies of `IntegerField` |
+| ~~Progress Bar~~ | `draw_line` + `EventQueue#tick_fps` | **built** 2026-08-02 (`D-progress-bar`, book ch7); a `value` that stays out of `HasValue`, ticker synced from `attached? && indeterminate?` |
 | Notification | `Popup` + `Ticker` | needs corner-anchored (non-centered) popup placement |
 | Confirm Dialog | `Popup`+`Window`+`Button` | fold `PickerWindow` in |
 | Details → Accordion | `HasContent` | Details is the atom, Accordion the group |
 | Tabs → Tabsheet | `HasValue` (index) + `HasContent` | strip, then strip + content swap |
-| Popover | extract `ComboBox#anchor` + `ListDropdown` geometry | generalize the anchored non-modal overlay; gates the next two |
+| 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. Gates the next two |
 | Menu Bar | `ListDropdown::Menu` + Popover | |
 | Context Menu | same | `:right` button already parses |
 | Slider | `draw_line` | arrows/PgUp; 25.2 also has a two-thumb *range* variant |
@@ -87,8 +91,13 @@ That leaves ~46 gaps.
 These are prerequisites, not components, and each deserves its own idea
 file when its cluster comes up:
 
-1. **Box layouts** (H/V) — everything form-shaped wants them.
-2. **Field label + helper text seam** → Form Layout.
+1. ~~**Box layouts** (H/V)~~ — **done** 2026-08-07 (`D-box-layouts`). Turned
+   out *not* to be structural: a `Box` is an `Absolute` subclass with a `rect=`
+   override, so it unblocked the form-shaped cluster without touching the
+   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.
 4. **Anchored Popover extraction** → Menu Bar, Context Menu, pickers,
    Tooltip.

data/lib/tuile/component/big_decimal_field.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+# The gem's one *optional* dependency, deliberately absent from the gemspec so
+# that only an app naming this component pays for it. Zeitwerk loads this file
+# on the first reference to {Tuile::Component::BigDecimalField} and not before.
+begin
+  require "bigdecimal"
+rescue LoadError
+  raise LoadError, "Tuile::Component::BigDecimalField needs the bigdecimal gem. Add `gem \"bigdecimal\"` " \
+                   "to your Gemfile — since Ruby 3.4 it is a bundled gem, so Bundler no longer puts it " \
+                   "on the load path for free."
+end
+
+module Tuile
+  class Component
+    # A single-line field whose {#value} is a `BigDecimal` (or `nil` when
+    # empty) — the numeric field for money, where {FloatField}'s binary double
+    # would round. Give it a single-row {#rect}:
+    #
+    #   price = Component::BigDecimalField.new
+    #   price.on_value_change = ->(d) { total.value = d }   # BigDecimal or nil
+    #   price.value = BigDecimal("19.99")                   # field shows "19.99"
+    #   price.value = 19.99                                 # ArgumentError: a Float can't be exact
+    #
+    # Only `0`–`9`, one leading `-` and one `.` can be typed; any other
+    # printable key is dropped without moving the caret. Up/Down step by one.
+    # Range checks (`min`/`max`) and a display scale (`19.9` → `19.90`) belong
+    # to a forms layer, not here — nothing rounds or pads what you typed.
+    #
+    # Requires the `bigdecimal` gem, which Tuile does *not* depend on: it is a
+    # bundled gem from Ruby 3.4 on, so a `Gemfile` naming it is what puts it on
+    # the load path. Referencing this class without it raises `LoadError`.
+    #
+    # == Implementation details
+    # {#value} is a *derived parse*: the buffer is the single source of truth,
+    # recomputed on read and left exactly as typed (`"19.90"` keeps its zero,
+    # which `BigDecimal#to_s` would not). It reads `nil` for a buffer that
+    # isn't a number (`""`, a lone `"-"`) but `1` / `0.5` for a half-typed
+    # `"1."` / `".5"`, so reaching for the decimal point doesn't blink the
+    # value to `nil` and back through {#on_value_change} — which fires per
+    # keystroke, but only on a real *value* change (`"1.0"`→`"1.00"` is silent,
+    # since the two compare equal).
+    #
+    # Both ends of that round-trip are written here rather than left to the
+    # library, because `bigdecimal` 3.1 (Ruby 3.3's default gem) and 4.x
+    # disagree about them: 3.1 rejects `BigDecimal("1.")` and `BigDecimal(0.1)`
+    # where 4.x accepts both. So the buffer is normalized before parsing, a
+    # `Float` is refused on both, and display goes through `to_s("F")` — plain
+    # notation, never `BigDecimal#to_s`'s `"0.1999e2"`.
+    #
+    # It *composes* a {TextField} (its single {HasContent} child) rather than
+    # subclassing one, so its face carries only the typed {HasValue} seam,
+    # never the widget's `String`-typed `text`.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class BigDecimalField < Component
+      include HasContent
+      include HasValue
+
+      # A buffer {#value} parses: an optional sign and digits with an optional
+      # fractional part (either side may be empty, but not both). No exponent —
+      # `to_s("F")` never writes one and no key types an `e`.
+      # @return [Regexp]
+      NUMERIC = /\A-?(?:\d+(?:\.\d*)?|\.\d+)\z/
+      private_constant :NUMERIC
+
+      def initialize
+        super()
+        @last_value = nil
+        field = TextField.new
+        field.on_change = ->(_text) { fire_if_changed }
+        field.on_key = method(:field_key)
+        self.content = field
+      end
+
+      # @return [::BigDecimal, nil] the parsed buffer; `nil` when empty or not a
+      #   number (e.g. a lone `"-"`).
+      def value
+        text = content.text
+        text.match?(NUMERIC) ? BigDecimal(normalize(text)) : nil
+      end
+
+      # Writes `new_value` into the buffer in plain notation and parks the
+      # caret at its end; fires {#on_value_change} only if the value actually
+      # changed.
+      # @param new_value [::BigDecimal, Integer, String, nil] `nil` empties the
+      #   field. A `Float` is refused, not converted — see the raise.
+      # @raise [ArgumentError] on a `Float` (its binary value is not the
+      #   decimal you wrote, which is the whole reason to use this field), a
+      #   non-numeric `String`, a NaN or an infinity.
+      # @raise [TypeError] on a value `BigDecimal()` won't take at all.
+      # @return [void]
+      def value=(new_value)
+        content.text = new_value.nil? ? "" : coerce(new_value).to_s("F")
+        content.caret = content.text.length
+      end
+
+      # `nil`, not `""`: a numeric field with no parseable number is empty.
+      # @return [nil]
+      def empty_value = nil
+
+      # @return [Point, nil] the field's caret (the hardware cursor is delegated
+      #   to the inner field).
+      def cursor_position = content.cursor_position
+
+      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      def on_enter = content.on_enter
+
+      # @param callback [Proc, Method, nil]
+      # @return [void]
+      def on_enter=(callback)
+        content.on_enter = callback
+      end
+
+      protected
+
+      # Places the wrapped field across the whole rect ({HasContent} hook).
+      # @param field [Component]
+      # @return [void]
+      def layout(field) = (field.rect = rect)
+
+      private
+
+      # Rewrites the half-typed shapes {NUMERIC} admits into ones every
+      # `bigdecimal` version parses: `".5"` → `"0.5"`, `"1."` → `"1"`.
+      # @param text [String] a buffer matching {NUMERIC}.
+      # @return [String]
+      def normalize(text)
+        text = text.sub(".", "0.") if text.start_with?(".", "-.")
+        text.chomp(".")
+      end
+
+      # @param new_value [::BigDecimal, Integer, String]
+      # @return [::BigDecimal]
+      # @raise [ArgumentError] on a `Float` — `bigdecimal` 4.x would take it
+      #   and 3.1 would not, and neither answer is the one a money field wants
+      #   to give silently. Also on a NaN or an infinity: `to_s("F")` writes
+      #   `"NaN"`, which no parse reads back, so writing one would silently
+      #   turn the value `nil`.
+      def coerce(new_value)
+        if new_value.is_a?(Float)
+          raise ArgumentError, "a Float is not exact — pass BigDecimal(#{new_value.to_s.inspect}) or the String"
+        end
+
+        big = BigDecimal(new_value)
+        raise ArgumentError, "value must be finite, got #{big}" unless big.finite?
+
+        big
+      end
+
+      # The field's key interceptor, consulted *before* the field acts on the
+      # key — which is what lets a rejected character be swallowed without the
+      # caret ever moving.
+      # @param key [String]
+      # @return [Boolean] true to consume the key.
+      def field_key(key)
+        case key
+        when Keys::UP_ARROW then step(1)
+        when Keys::DOWN_ARROW then step(-1)
+        else return Keys.printable?(key) && !accepts?(key)
+        end
+        true
+      end
+
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as
+      # zero.
+      # @param delta [Integer]
+      # @return [void]
+      def step(delta) = (self.value = (value || BigDecimal(0)) + delta)
+
+      # Whether `char` may be inserted. Deliberately shallow: it keeps the
+      # buffer *typeable* rather than always-valid — a transient `"-"` or
+      # `"1."` has to be reachable — and {#value} decides what parses.
+      # @param char [String] a single printable character.
+      # @return [Boolean]
+      def accepts?(char)
+        case char
+        when /\A[0-9]\z/ then true
+        when "-" then content.caret.zero? && !content.text.start_with?("-")
+        when "." then !content.text.include?(".")
+        else false
+        end
+      end
+
+      # Re-emits {#on_value_change} with the freshly-parsed {#value}, but only
+      # when it differs from the last one fired — so a buffer edit that leaves
+      # the value unchanged (`"1.0"`→`"1.00"`) 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

data/lib/tuile/component/checkbox.rb

@@ -2,7 +2,7 @@
 
 module Tuile
   class Component
-    # A boolean input on one row. Space or a left click toggles it:
+    # A boolean input on one row. Space, Enter or a left click toggles it:
     #
     #   [x] Enable syslog forwarding
     #   [ ] Enable syslog forwarding
@@ -18,11 +18,12 @@ module Tuile
     # {#empty_value}, so a fresh checkbox is {HasValue#empty? empty} and
     # {HasValue#clear} unchecks.
     #
-    # Space toggles. Enter is unhandled — unlike {Button} — simply because a
-    # checkbox has no default action to confirm, so it bubbles to an ancestor;
-    # treat that as this widget declining a key, not as a guarantee the framework
-    # makes (a {TextArea} claims Enter for newline, and a checkable row in a
-    # {Component::List} toggles on it).
+    # Space and Enter both toggle — same as a checkable row in a
+    # {Component::List} ({CheckboxGroup}, {RadioGroup}), so the gesture reads the
+    # same standalone and grouped. A focused checkbox therefore *consumes* Enter:
+    # a form's Enter-to-submit on an ancestor won't see it, exactly as with a
+    # focused {Button} or {TextArea}. Which widget lets Enter through is per
+    # widget, never a framework guarantee — book ch5's Enter table is the list.
     #
     # A tab stop, so Tab lands on it, and the widget highlights while on the focus
     # chain. Assign a {#rect} (typically from the surrounding {Layout}) at least
@@ -97,12 +98,12 @@ module Tuile
       # @return [Rect]
       def extent = Rect.new(rect.left, rect.top, [caption.display_width + 4, rect.width].min, 1)
 
-      # Toggles on Space. Every other key — Enter included — is left unhandled so
-      # it bubbles to an ancestor.
+      # Toggles on Space or Enter. Every other key is left unhandled so it bubbles
+      # to an ancestor.
       # @param key [String]
       # @return [Boolean]
       def handle_key(key)
-        return false unless key == " "
+        return false unless [" ", Keys::ENTER].include?(key)
 
         toggle
         true

data/lib/tuile/component/combo_box.rb

@@ -147,11 +147,12 @@ module Tuile
       protected
 
       # Field spans the row bar the last column, which the `▾` occupies
-      # ({HasContent} layout hook).
+      # ({HasContent} layout hook). One row, or none at all when the combo itself
+      # was given none — a starved parent must not hand out a rect it doesn't own.
       # @param field [Component]
       # @return [void]
       def layout(field)
-        field.rect = Rect.new(rect.left, rect.top, [rect.width - 1, 0].max, 1)
+        field.rect = Rect.new(rect.left, rect.top, [rect.width - 1, 0].max, [rect.height, 1].min)
       end
 
       private
@@ -251,31 +252,12 @@ module Tuile
       # @return [String] the plain-text label for `item`, or "" for nil.
       def display_for(item) = item.nil? ? "" : @item_label.call(item).to_s
 
-      # Sizes and positions the dropdown against the field: full combo width,
-      # `min(matches, 10)` rows, below the field — flipped above when it won't
-      # fit beneath, clamped (with the list scrolling) when it fits neither.
+      # Places the dropdown at the combo's own width, so both its edges line up
+      # with the field — at the cost of the scrollbar taking its column from the
+      # labels, which ellipsize a column earlier once the list scrolls. That is
+      # the trade a measuring driver ({Select}) makes the other way.
       # @return [void]
-      def anchor
-        desired = [@filtered.size, MAX_VISIBLE_ROWS].min
-        below = screen.size.height - (rect.top + 1)
-        above = rect.top
-        if desired <= below
-          top = rect.top + 1
-          height = desired
-        elsif above >= below
-          height = [desired, above].min
-          top = rect.top - height
-        else
-          height = below
-          top = rect.top + 1
-        end
-        @overlay.size = Size.new(rect.width, height)
-        @overlay.rect = Rect.new(rect.left, top, rect.width, height)
-      end
-
-      # Most matches shown before the dropdown scrolls.
-      # @return [Integer]
-      MAX_VISIBLE_ROWS = 10
+      def anchor = @overlay.anchor_to(rect, rows: @filtered.size)
     end
   end
 end