tuile 0.10.0 → 0.11.0

data/sig/tuile.rbs

@@ -2227,7 +2227,13 @@ module Tuile
     end
 
     # A layout doesn't paint anything by itself: its job is to position child
-    # components.
+    # components. Two families, both top-down (see book ch3):
+    # 
+    # - {Absolute} — you override {Component#rect=} and compute every child's
+    #   rectangle yourself. Total control, and the base for anything unusual.
+    # - {Box} / {Vertical} / {Horizontal} — you declare each child's extent as
+    #   a {Fixed}, {Percent} or {Expand} constraint and the layout does the
+    #   arithmetic. Sugar over the same `rect=` assignment, for the common case.
     # 
     # Children that fully tile the layout's rect repaint themselves and
     # cover everything; children that leave gaps (e.g. a form with widgets
@@ -2260,10 +2266,563 @@ module Tuile
 
       def on_focus: () -> void
 
+      # How much space a child gets along one axis of a {Box}: exactly {#cells},
+      # clamped to whatever is still unassigned.
+      # 
+      #   add(prompt, Fixed[4])                    # 4 rows in a Vertical
+      #   add(field, Fixed[1], cross: Fixed[30])   # 1 row, 30 columns wide
+      # 
+      # `Fixed[0]` hides the child — it gets an empty rect and paints nothing.
+      # 
+      # @!attribute [r] cells
+      #   @return [Integer] cell count along the axis.
+      class Fixed
+        # _@param_ `cells` — cell count along the axis; `>= 0`.
+        def initialize: (cells: Integer) -> void
+
+        # _@return_ — cell count along the axis.
+        attr_reader cells: Integer
+      end
+
+      # A percentage of the space *available* along a {Box}'s axis — measured
+      # after {Box#padding} and {Box#spacing} have come off, so two `Percent[50]`
+      # children fit exactly rather than overflowing by the gap between them.
+      # 
+      #   add(left, Percent[60])
+      #   add(right, Percent[40])
+      # 
+      # @!attribute [r] percent
+      #   @return [Numeric] percentage of the available extent, `0..100`.
+      class Percent
+        # _@param_ `percent` — percentage of the available extent, `0..100`.
+        def initialize: (percent: Numeric) -> void
+
+        # _@return_ — percentage of the available extent, `0..100`.
+        attr_reader percent: Numeric
+      end
+
+      # A share of whatever a {Box} has left once its {Fixed} and {Percent}
+      # children have taken theirs, split between the `Expand` children in
+      # proportion to their weights:
+      # 
+      #   add(header, Fixed[1])
+      #   add(body, Expand[2])    # gets twice…
+      #   add(side, Expand[1])    # …what this one gets
+      # 
+      # Main axis only — {Box#add} rejects one passed as `cross:`, where a child
+      # has no siblings to compete with and so nothing for a weight to mean.
+      # 
+      # @!attribute [r] weight
+      #   @return [Integer] relative share of the leftover space.
+      class Expand
+        # _@param_ `weight` — relative share; `>= 1`.
+        def initialize: (weight: Integer) -> void
+
+        # _@return_ — relative share of the leftover space.
+        attr_reader weight: Integer
+      end
+
+      # Per-edge padding for a {Box}, in cells:
+      # 
+      #   Insets[top: 1]                     # one blank row above the children
+      #   Insets[top: 1, left: 2, right: 2]  # unnamed edges default to 0
+      #   Insets.coerce(1)                   # uniform on all four edges
+      # 
+      # Keyword-only: AWT and JavaFX order these same four numbers differently,
+      # so a positional form would be a coin flip.
+      # 
+      # @!attribute [r] top
+      #   @return [Integer] cells inset from the top edge.
+      # @!attribute [r] right
+      #   @return [Integer] cells inset from the right edge.
+      # @!attribute [r] bottom
+      #   @return [Integer] cells inset from the bottom edge.
+      # @!attribute [r] left
+      #   @return [Integer] cells inset from the left edge.
+      class Insets
+        ZERO: Insets
+
+        # _@param_ `positional` — must be empty — see the class doc.
+        # 
+        # _@param_ `kwargs` — any of `top:`/`right:`/`bottom:`/`left:`.
+        def self.new: (*::Array[untyped] positional, **::Hash[Symbol, Integer] kwargs) -> Insets
+
+        # Needed because `Data`'s inherited `[]` never dispatches through a `new`
+        # override, so the guard above alone would miss `Insets[1, 2, 3, 4]`.
+        # 
+        # _@param_ `positional` — must be empty.
+        # 
+        # _@param_ `kwargs` — any of `top:`/`right:`/`bottom:`/`left:`.
+        def self.[]: (*::Array[untyped] positional, **::Hash[Symbol, Integer] kwargs) -> Insets
+
+        # _@param_ `value` — an Integer becomes a uniform inset.
+        def self.coerce: ((Insets | Integer) value) -> Insets
+
+        # _@param_ `top` — cells inset from the top edge; `>= 0`.
+        # 
+        # _@param_ `right` — cells inset from the right edge; `>= 0`.
+        # 
+        # _@param_ `bottom` — cells inset from the bottom edge; `>= 0`.
+        # 
+        # _@param_ `left` — cells inset from the left edge; `>= 0`.
+        def initialize: (
+                          ?_top: Integer,
+                          ?right: Integer,
+                          ?bottom: Integer,
+                          ?left: Integer
+                        ) -> void
+
+        # _@return_ — `left` + `right`.
+        def horizontal: () -> Integer
+
+        # _@return_ — `top` + `bottom`.
+        def vertical: () -> Integer
+
+        # _@return_ — cells inset from the top edge.
+        attr_reader top: Integer
+
+        # _@return_ — cells inset from the right edge.
+        attr_reader right: Integer
+
+        # _@return_ — cells inset from the bottom edge.
+        attr_reader bottom: Integer
+
+        # _@return_ — cells inset from the left edge.
+        attr_reader left: Integer
+      end
+
       # Absolute layout. Extend this class, register any children, and
       # override {Component#rect=} to reposition the children.
       class Absolute < Layout
       end
+
+      # Abstract base of the one-dimensional box layouts. Children are stacked
+      # along a *main* axis in the order they were added, each getting the extent
+      # its constraint asks for; across the *cross* axis they are sized one at a
+      # time, since nothing competes with them there. {Vertical} and {Horizontal}
+      # pick which axis is which.
+      # 
+      #   class LoginForm < Tuile::Component::Layout::Vertical
+      #     def initialize
+      #       super(spacing: 1, padding: Insets[top: 1])
+      #       add(@prompt = Tuile::Component::Label.new, Fixed[4])
+      #       add(@user = Tuile::Component::TextField.new, Fixed[1], cross: Fixed[30])
+      #       add(@log = Tuile::Component::TextView.new, Expand[1])
+      #     end
+      #   end
+      # 
+      # The constraint names need no prefix inside a subclass — Ruby finds them on
+      # `Layout`, an ancestor. Component classes are not on that chain and still do.
+      # 
+      # Children pack from the start edge, so with no {Expand} among them the
+      # slack is simply left at the end: there is no filler component to add.
+      # Nest boxes to vary the gap — a `Vertical.new(spacing: 0)` inside a
+      # `Vertical.new(spacing: 1)` groups two rows tightly within a looser stack.
+      # 
+      # == Implementation details
+      # 
+      # Every child-list mutation re-runs the whole pass, because in a box the
+      # children move: removing one shifts everything after it, and adding one
+      # shrinks every {Expand} share. ({Absolute} can skip this — there, siblings
+      # are independent.)
+      # 
+      # Main-axis resolution order, against
+      # `available = extent - padding - spacing * (children - 1)`:
+      # 
+      # 1. {Fixed} takes its cells, clamped to what is still unassigned.
+      # 2. {Percent} takes its share *of `available`*, likewise clamped.
+      # 3. {Expand} children split the residue by weight; the integer remainder
+      #    goes to the earliest of them, one cell each.
+      # 
+      # So over-subscription starves in declaration order rather than raising:
+      # a child with nothing left gets an empty rect and paints nothing. Padding
+      # wider than the layout does the same to every child.
+      class Box < Layout
+        DEFAULT_PLACEMENT: ::Hash[Symbol, Object]
+        ALIGNMENTS: ::Array[Symbol]
+
+        # _@param_ `spacing` — blank cells between adjacent children; `>= 0`.
+        # 
+        # _@param_ `padding` — inset from this layout's own rect; an Integer is coerced to a uniform {Insets}.
+        def initialize: (?spacing: Integer, ?padding: (Insets | Integer)) -> void
+
+        # Adds a child — or every element of an Enumerable, all with the same
+        # constraints — and re-runs the layout.
+        # 
+        #   add(field, Fixed[1], cross: Fixed[30], align: :center)
+        #   add([ok, cancel], Fixed[1])
+        # 
+        # _@param_ `child`
+        # 
+        # _@param_ `main` — extent along the main axis.
+        # 
+        # _@param_ `cross` — extent across it.
+        # 
+        # _@param_ `align` — one of {ALIGNMENTS} — where a child narrower than the cross extent sits. {Vertical} / {Horizontal} say which edge `:start` is.
+        def add: (
+                   (Component | ::Enumerable[Component]) child,
+                   ?(Fixed | Percent | Expand) main,
+                   ?cross: (Fixed | Percent),
+                   ?align: Symbol
+                 ) -> void
+
+        # Removes the child, forgets its constraints, and closes the gap it left
+        # by re-running the layout.
+        # 
+        # _@param_ `child`
+        def remove: (Component child) -> void
+
+        # _@param_ `new_rect`
+        def rect=: (Rect new_rect) -> void
+
+        # Recomputes and assigns every child's rect. Silent until this layout has
+        # a rect of its own — {#add} runs during construction, long before a
+        # parent assigns one.
+        def relayout: () -> void
+
+        # _@return_ — {#rect} with {#padding} taken off each edge; may be
+        # {Rect#empty? empty}.
+        def inner_rect: () -> Rect
+
+        # _@param_ `inner` — {#inner_rect}, known non-empty.
+        def place_children: (Rect inner) -> void
+
+        # _@param_ `inner` — {#inner_rect}.
+        # 
+        # _@return_ — main-axis extent per child, in child order.
+        def main_sizes: (Rect inner) -> ::Array[Integer]
+
+        # Splits `slack` between the {Expand} children by weight, writing the
+        # results into `sizes`.
+        # 
+        # _@param_ `sizes` — mutated in place.
+        # 
+        # _@param_ `indices` — child indices carrying an {Expand}.
+        # 
+        # _@param_ `slack` — cells left over; a negative value yields zeroes.
+        def distribute_expand: (::Array[Integer] sizes, ::Array[Integer] indices, Integer slack) -> void
+
+        # _@param_ `child`
+        # 
+        # _@param_ `available` — cross extent of {#inner_rect}.
+        # 
+        # _@return_ — offset from `inner`'s start edge, and
+        # extent, along the cross axis.
+        def cross_placement: (Component child, Integer available) -> [Integer, Integer]
+
+        # _@param_ `align` — one of {ALIGNMENTS}.
+        # 
+        # _@param_ `slack` — unused cells across the axis.
+        def align_offset: (Symbol align, Integer slack) -> Integer
+
+        # _@param_ `extent`
+        # 
+        # _@param_ `constraint`
+        def percent_of: (Integer extent, Percent constraint) -> Integer
+
+        # _@param_ `child`
+        # 
+        # _@return_ — the child's `main`/`cross`/`align`.
+        def placement: (Component child) -> ::Hash[Symbol, Object]
+
+        # _@param_ `rect`
+        # 
+        # _@return_ — the extent along the main axis.
+        def main_extent: (Rect rect) -> Integer
+
+        # _@param_ `rect`
+        # 
+        # _@return_ — the extent along the cross axis.
+        def cross_extent: (Rect rect) -> Integer
+
+        # _@param_ `inner` — {#inner_rect}, the origin both offsets are relative to.
+        # 
+        # _@param_ `main_offset` — cells along the main axis.
+        # 
+        # _@param_ `main_size` — extent along the main axis.
+        # 
+        # _@param_ `cross_offset` — cells along the cross axis.
+        # 
+        # _@param_ `cross_size` — extent along the cross axis.
+        # 
+        # _@return_ — absolute screen rect for one child.
+        def build_rect: (
+                          Rect inner,
+                          Integer main_offset,
+                          Integer main_size,
+                          Integer cross_offset,
+                          Integer cross_size
+                        ) -> Rect
+
+        # _@param_ `cells`
+        # 
+        # _@return_ — `cells`.
+        def validate_spacing: (Integer cells) -> Integer
+
+        # _@param_ `constraint`
+        def validate_main: (Object constraint) -> void
+
+        # _@param_ `constraint`
+        def validate_cross: (Object constraint) -> void
+
+        # _@param_ `align`
+        def validate_align: (Object align) -> void
+
+        # _@return_ — blank cells between adjacent children.
+        attr_accessor spacing: Integer
+
+        # _@return_ — inset from this layout's own rect.
+        attr_accessor padding: (Insets | Integer)
+      end
+
+      # Stacks children top to bottom. The main axis is vertical, so a child's
+      # positional constraint is its **height** and `cross:` is its **width**;
+      # `align: :start` is the left edge, `:end` the right.
+      # 
+      #   form = Component::Layout::Vertical.new(spacing: 1)
+      #   form.add(caption, Component::Layout::Fixed[1])
+      #   form.add(field, Component::Layout::Fixed[1], cross: Component::Layout::Fixed[30])
+      #   form.add(log, Component::Layout::Expand[1])   # takes whatever is left below
+      # 
+      # Inside a subclass the constraints need no prefix at all — see {Box}.
+      # 
+      # See {Box} for the constraint vocabulary and how the space is divided.
+      class Vertical < Tuile::Component::Layout::Box
+        DEFAULT_PLACEMENT: ::Hash[Symbol, Object]
+        ALIGNMENTS: ::Array[Symbol]
+
+        # _@param_ `rect`
+        def main_extent: (Rect rect) -> Integer
+
+        # _@param_ `rect`
+        def cross_extent: (Rect rect) -> Integer
+
+        # _@param_ `inner`
+        # 
+        # _@param_ `main_offset` — rows down from `inner`'s top.
+        # 
+        # _@param_ `main_size` — height.
+        # 
+        # _@param_ `cross_offset` — columns right of `inner`'s left.
+        # 
+        # _@param_ `cross_size` — width.
+        def build_rect: (
+                          Rect inner,
+                          Integer main_offset,
+                          Integer main_size,
+                          Integer cross_offset,
+                          Integer cross_size
+                        ) -> Rect
+      end
+
+      # Lays children out left to right. The main axis is horizontal, so a
+      # child's positional constraint is its **width** and `cross:` is its
+      # **height**; `align: :start` is the top edge, `:end` the bottom.
+      # 
+      #   split = Component::Layout::Horizontal.new
+      #   split.add(sidebar, Component::Layout::Fixed[30])
+      #   split.add(main, Component::Layout::Expand[1])   # takes the rest of the row
+      # 
+      # Inside a subclass the constraints need no prefix at all — see {Box}.
+      # 
+      # See {Box} for the constraint vocabulary and how the space is divided.
+      class Horizontal < Tuile::Component::Layout::Box
+        DEFAULT_PLACEMENT: ::Hash[Symbol, Object]
+        ALIGNMENTS: ::Array[Symbol]
+
+        # _@param_ `rect`
+        def main_extent: (Rect rect) -> Integer
+
+        # _@param_ `rect`
+        def cross_extent: (Rect rect) -> Integer
+
+        # _@param_ `inner`
+        # 
+        # _@param_ `main_offset` — columns right of `inner`'s left.
+        # 
+        # _@param_ `main_size` — width.
+        # 
+        # _@param_ `cross_offset` — rows down from `inner`'s top.
+        # 
+        # _@param_ `cross_size` — height.
+        def build_rect: (
+                          Rect inner,
+                          Integer main_offset,
+                          Integer main_size,
+                          Integer cross_offset,
+                          Integer cross_size
+                        ) -> Rect
+      end
+    end
+
+    # A closed-choice field on one row: the selected item's label plus a `▾`
+    # affordance, dropping open a {ListDropdown} of the options. Enter, Space or
+    # Down opens it; the arrows (and PgUp/PgDn) move the highlight; Enter or
+    # Space commits; ESC dismisses without committing.
+    # 
+    #   warn                ▾     <- the face: one row, on a field well
+    #    debug                    <- the dropdown, measured to the widest label
+    #    info                        (the one-column gutters are {List}'s)
+    #    warn                     <- highlighted: the value's row, on open
+    #    error
+    # 
+    #   sel = Component::Select.new(items: LogLevel.all)
+    #   sel.item_label = ->(l) { l.name }          # item -> shown label; default :to_s
+    #   sel.on_value_change = ->(l) { relog(l) }   # fires on commit, with the item
+    #   sel.value = LogLevel::WARN                 # selects it; the face shows its label
+    # 
+    # Use it for an **enum** — labels the developer authored, a closed set known
+    # when the code is written: log level, sort order, line endings, Yes/No/Ask.
+    # For items the app supplies at runtime with labels you don't control
+    # (countries, users, branches) reach for {ComboBox} instead, where filtering
+    # is the navigation. Item count is a symptom, not the criterion; book ch7 has
+    # the widget-choice table.
+    # 
+    # {#value} is the selected *item*, of whatever type {#items} holds, never its
+    # label; `nil` — a blank face — is the initial state and stays legal, so an
+    # optional enum field needs no placeholder. As on {ComboBox}, {#items=} is
+    # chrome: it never touches {#value}, never fires {HasValue#on_value_change},
+    # and a value absent from {#items} survives intact while rendering nothing
+    # selected. Keeping the two in sync is the app's job.
+    # 
+    # == It claims no printable key but Space
+    # Enter, Space, ESC, {ListDropdown::MOVE_KEYS} and the mouse. *Every other*
+    # printable key bubbles past it (key-dispatch rung 3), so a form's `s`-to-save
+    # and a layout's `1`/`2`/`3` pane jumps keep working while a Select has focus
+    # — the one capability no {ComboBox} configuration can offer, since a text
+    # field eats printables unconditionally. Space is the single exception, and it
+    # forecloses nothing: every activatable widget in the gem already claims it.
+    # Home/End are declined too, so they stay available app-wide.
+    # 
+    # There is no type-ahead: a hidden prefix buffer *is* the ComboBox query with
+    # the feedback removed (`DECISIONS.md` `D-select`). Which is also why labels
+    # need no prefix-disambiguation.
+    # 
+    # == Implementation details
+    # A leaf widget: it paints its own row (the face is *derived* from {#value}
+    # each paint, never a synced copy) and owns the dropdown as an overlay, which
+    # is not a child — like {ComboBox}'s. The well is read from
+    # {Screen#theme} at paint time, so it tracks a theme flip with no hook.
+    # 
+    # The dropdown is at least as wide as the face and grows to fit the widest
+    # label, so the labels are never the thing that ellipsizes. It is not opened
+    # at all when {#items} is empty: an item-less Select is a programming bug, and
+    # an empty tinted panel reads as a broken list rather than as "nothing to
+    # pick". Enter/Space/Down are claimed either way.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class Select < Component
+      include Tuile::Component::HasValue
+
+      # _@param_ `items` — the options (any type); also settable via {#items=}.
+      # 
+      # _@param_ `value` — the initially selected item. Seeds the backing ivar directly, so no listener fires and assignment order doesn't matter to a form helper.
+      def initialize: (?items: ::Array[untyped], ?value: Object?) -> void
+
+      def tab_stop?: () -> bool
+
+      def keyboard_hint: () -> String
+
+      # Re-anchors the (open) dropdown after a move or resize.
+      # 
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
+
+      # Closes the dropdown when the Select leaves the focus chain, so tabbing
+      # away doesn't strand an open menu. Safe against re-entrancy: focus never
+      # sits inside the (non-focusable) {ListDropdown}, so closing it repairs no
+      # focus.
+      # 
+      # _@param_ `flag`
+      def active=: (bool flag) -> void
+
+      # Opens the dropdown on Enter, Space or Down; while it is open, forwards
+      # {ListDropdown::MOVE_KEYS} to it, commits the highlight on Enter or Space,
+      # and dismisses on ESC. Everything else — every other printable included —
+      # is left unhandled so it bubbles to an ancestor.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Toggles the dropdown on a left click anywhere in {#rect} — a field's
+      # affordance is its whole row, as the well advertises; `super` runs first,
+      # so the click also focuses.
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # The painted row: the value's label padded across all but the last column,
+      # then the `▾`, all on the field well — {Theme#active_bg_color} while on the
+      # focus chain, {Theme#input_bg_color} otherwise.
+      def face_row: () -> StyledString
+
+      # Rebuilds the dropdown's rows, highlight and geometry, opening it if
+      # needed; closes it instead when there is nothing to show.
+      def refill: () -> void
+
+      def open_menu: () -> void
+
+      def close_menu: () -> void
+
+      # Adopts the item on row `index` as {#value} and closes the dropdown.
+      # 
+      # _@param_ `index`
+      def commit: (Integer index) -> void
+
+      def anchor: () -> void
+
+      # The dropdown's width: the widest label plus {List}'s two row gutters, plus
+      # the scrollbar column when the rows can't all be shown at once — but never
+      # narrower than the Select itself, so both edges line up with the face and
+      # the panel reads as belonging to it. Only a label that needs more pushes it
+      # wider.
+      # 
+      # A dropdown the screen clamps shorter than
+      # {ListDropdown::MAX_VISIBLE_ROWS} scrolls without having bought that
+      # column, ellipsizing its labels one early — the {ComboBox} trade, in the
+      # one case measuring can't predict the height.
+      def menu_width: () -> Integer
+
+      # _@param_ `item`
+      # 
+      # _@return_ — `item`'s label, or empty for `nil` — so {#value}
+      # being unset never reaches an {#item_label} that assumes an item.
+      def label_for: (Object item) -> StyledString
+
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
+
+      # No-op (no repaint, no listener) when equal to the current value.
+      # 
+      # _@param_ `new_value`
+      def value=: (Object new_value) -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # _@return_ — the value {#empty?}/{#clear} treat as empty; `nil`
+      # unless an includer overrides it.
+      def empty_value: () -> Object
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@return_ — the options.
+      attr_accessor items: ::Array[untyped]
+
+      # _@return_ — item -> shown label (a `String` or
+      # {StyledString}); `:to_s` by default. Never called with `nil` — an
+      # unselected Select renders a blank face.
+      attr_accessor item_label: (Proc | Method)
     end
 
     # A window with a frame, a {#caption} and a content {Component}. Doesn't
@@ -2366,7 +2925,7 @@ module Tuile
       attr_accessor footer_text: (StyledString | String)?
     end
 
-    # 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
@@ -2382,11 +2941,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
@@ -2449,8 +3009,8 @@ module Tuile
       # mode switch invisible in the code and untestable by inspection.
       def extent: () -> Rect
 
-      # 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`
       def handle_key: (String key) -> bool
@@ -2525,7 +3085,6 @@ module Tuile
     class ComboBox < Component
       include Tuile::Component::HasContent
       include Tuile::Component::HasValue
-      MAX_VISIBLE_ROWS: Integer
 
       # _@param_ `items` — the candidate items (any type); also settable via {#items=}.
       def initialize: (?items: ::Array[untyped]) -> void
@@ -2564,7 +3123,8 @@ module Tuile
       def repaint: () -> void
 
       # 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`
       def layout: (Component field) -> void
@@ -2618,9 +3178,10 @@ module Tuile
       # _@return_ — the plain-text label for `item`, or "" for nil.
       def display_for: (Object item) -> String
 
-      # 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.
       def anchor: () -> void
 
       # _@return_ — the current value; `nil` until first set.
@@ -3555,6 +4116,126 @@ module Tuile
       attr_accessor on_enter: (Proc | Method)?
     end
 
+    # A single-line field whose {#value} is a `Float` (or `nil` when empty) —
+    # the {IntegerField} twin, one Ruby type over. Give it a single-row {#rect}:
+    # 
+    #   field = Component::FloatField.new
+    #   field.on_value_change = ->(x) { puts x.inspect }  # Float or nil, per change
+    #   field.value = 19.99                               # field shows "19.99"
+    #   field.clear                                       # empties it; value => nil
+    # 
+    # Only `0`–`9`, one leading `-` and one `.` can be typed; any other
+    # printable key is dropped without moving the caret. Up/Down step by `1.0`
+    # (an empty field counting as `0.0`). A `Float` is a binary double, so this
+    # is the wrong field for money — hold that as `Integer` cents in an
+    # {IntegerField} — and range checks (`min`/`max`) belong to a forms layer,
+    # not here.
+    # 
+    # == Implementation details
+    # {#value} is a *derived parse*: the buffer is the single source of truth,
+    # recomputed on read and left exactly as typed (`"007"` keeps its zeros).
+    # It reads `nil` for a buffer that isn't a number (`""`, a lone `"-"`) but
+    # `1.0` / `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 (`"7"`→`"07"` is silent). The parse also accepts the exponent
+    # `Float#to_s` writes for extreme magnitudes, so `value = 1e-5` round-trips
+    # through the `"1.0e-05"` it displays, though no key types an `e`.
+    # 
+    # 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 FloatField < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+      NUMERIC: Regexp
+
+      def initialize: () -> void
+
+      # _@return_ — the parsed buffer; `nil` when empty or not a
+      # number (e.g. a lone `"-"`).
+      def value: () -> Float?
+
+      # Writes `new_value` into the buffer and parks the caret at its end; fires
+      # {#on_value_change} only if the value actually changed.
+      # 
+      # _@param_ `new_value` — `nil` empties the field; anything else is coerced with `Float()`, so an `Integer` `3` shows as `"3.0"`.
+      def value=: (Numeric? new_value) -> void
+
+      # `nil`, not `""`: a numeric field with no parseable number is empty.
+      def empty_value: () -> void
+
+      # _@return_ — the field's caret (the hardware cursor is delegated
+      # to the inner field).
+      def cursor_position: () -> Point?
+
+      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      def on_enter: () -> (Proc | Method)?
+
+      # _@param_ `callback`
+      def on_enter=: ((Proc | Method)? callback) -> void
+
+      # Places the wrapped field across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `field`
+      def layout: (Component field) -> void
+
+      # _@param_ `new_value`
+      def coerce: (Numeric new_value) -> Float
+
+      # 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`
+      # 
+      # _@return_ — true to consume the key.
+      def field_key: (String key) -> bool
+
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as
+      # `0.0`.
+      # 
+      # _@param_ `delta`
+      def step: (Float delta) -> void
+
+      # 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` — a single printable character.
+      def accepts?: (String char) -> bool
+
+      # 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 (`"7"`→`"07"`) stays silent.
+      def fire_if_changed: () -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+    end
+
     # The chrome text a component *wears* — a {Window}'s border title, a
     # {Button}'s label — as opposed to the value it *holds*.
     # 
@@ -4023,26 +4704,27 @@ module Tuile
     end
 
     # A borderless, tinted, non-focusable floating selection list — the dropdown
-    # a text input drops open, drives by forwarding movement keys, and commits a
+    # a *driver* drops open, drives by forwarding movement keys, and commits a
     # pick from: a non-modal {Popup} wrapping a {List} that never takes focus, so
-    # the caret stays in the driving input while the caller refills the rows,
-    # moves the highlight, and reads the pick.
+    # focus stays on the driver while the caller refills the rows, moves the
+    # highlight, and reads the pick.
     # 
     #   drop = Component::ListDropdown.new
     #   drop.on_item_chosen = ->(index, _line) { commit(index) } # caller commits
-    #   # …then, per keystroke in the driving input's key handler:
-    #   drop.lines = matches.map { |m| render(m) }  # caller filters + renders
-    #   drop.rect  = Rect.new(...)                   # caller anchors + sizes it
+    #   # …then, from the driver's key handler:
+    #   drop.lines = matches.map { |m| render(m) }   # caller filters + renders
+    #   drop.anchor_to(rect, rows: matches.size)     # below the driver, or flipped
     #   drop.open
     #   return true if drop.move(key)  # Up/Down/PgUp/PgDn/^U/^D → list scroll
     #   drop.choose if key == Keys::ENTER            # commit the highlight
     # 
-    # It owns only what every such dropdown shares; everything that varies stays
-    # with the driver: geometry/anchoring, filtering, row rendering, the commit
-    # action, and ESC/Enter handling. ESC and Enter carry driver-specific tails
-    # (ESC may revert a query; Enter may commit via {#choose} *or* via a separate
-    # submit path), so {#move} claims neither — the driver calls {#choose} and
-    # {#close} from its own branches.
+    # It owns only what every such dropdown shares — *placement* included, via
+    # {#anchor_to}. What stays with the driver: the width **policy** ({#anchor_to}
+    # measures nothing itself), filtering, row rendering, the commit action, and
+    # ESC/Enter handling. ESC and Enter carry driver-specific tails (ESC may
+    # revert a query; Enter may commit via {#choose} *or* via a separate submit
+    # path), so {#move} claims neither — the driver calls {#choose} and {#close}
+    # from its own branches.
     # 
     # == Theming
     # Borderless, told apart from the content beneath by a background tint —
@@ -4053,6 +4735,7 @@ module Tuile
     # UI-thread-confined, like every component (see {Screen}).
     class ListDropdown < Tuile::Component::Popup
       MOVE_KEYS: ::Array[String]
+      MAX_VISIBLE_ROWS: Integer
 
       def initialize: () -> void
 
@@ -4071,6 +4754,31 @@ module Tuile
       # _@return_ — the list's cursor (the current highlight).
       def cursor: () -> List::Cursor
 
+      # Sizes and places the dropdown against `anchor`: directly beneath it,
+      # flipped above when `rows` won't fit below, clamped — with the list
+      # scrolling — when neither side has room. Horizontally the left edges line
+      # up, sliding left only far enough to keep the panel on screen.
+      # 
+      #   drop.anchor_to(field.rect, rows: matches.size)            # field width
+      #   drop.anchor_to(rect, rows: items.size, width: measured)   # own width
+      # 
+      # Vertical flips but horizontal slides because covering the driver would
+      # hide what is being chosen, while sharing its columns is the point.
+      # 
+      # _@param_ `anchor` — the driver's rect; the dropdown never covers it.
+      # 
+      # _@param_ `rows` — how many rows there are to show — the content count, not the height: more than fits turns the scrollbar on. `0` collapses the dropdown to an empty rect (drivers close instead).
+      # 
+      # _@param_ `width` — the panel's width in columns, clamped to the screen. Defaults to the anchor's, which lines both edges up with a field; a driver that measured its labels passes its own. A label wider than the screen clips — {List} has no horizontal scrolling.
+      # 
+      # _@param_ `max_rows` — rows shown before the list scrolls.
+      def anchor_to: (
+                       Rect anchor,
+                       rows: Integer,
+                       ?width: Integer,
+                       ?max_rows: Integer
+                     ) -> void
+
       # Forwards a cursor-movement key to the list. The driver calls this from
       # its own key handler; a truthy return means "consumed — stop here", falsy
       # means "not mine — proceed with normal editing/dispatch". Only {MOVE_KEYS}
@@ -4090,8 +4798,8 @@ module Tuile
       def choose: () -> bool
 
       # The dropdown's {List}. Non-focusable on purpose: the driver forwards keys
-      # while focus (and the caret) stay in its input, and a mouse click selects
-      # an item without stealing focus — so the input never loses the cursor
+      # while focus stays on it, and a mouse click selects an item without
+      # stealing focus — so a driving text input never loses its caret
       # mid-interaction.
       class Menu < Tuile::Component::List
         def focusable?: () -> bool
@@ -4342,6 +5050,142 @@ module Tuile
       attr_accessor revealed: (bool | Object)
     end
 
+    # 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 Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+      NUMERIC: Regexp
+
+      def initialize: () -> void
+
+      # _@return_ — the parsed buffer; `nil` when empty or not a
+      # number (e.g. a lone `"-"`).
+      def value: () -> ::BigDecimal?
+
+      # 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` — `nil` empties the field. A `Float` is refused, not converted — see the raise.
+      def value=: ((::BigDecimal | Integer | String)? new_value) -> void
+
+      # `nil`, not `""`: a numeric field with no parseable number is empty.
+      def empty_value: () -> void
+
+      # _@return_ — the field's caret (the hardware cursor is delegated
+      # to the inner field).
+      def cursor_position: () -> Point?
+
+      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      def on_enter: () -> (Proc | Method)?
+
+      # _@param_ `callback`
+      def on_enter=: ((Proc | Method)? callback) -> void
+
+      # Places the wrapped field across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `field`
+      def layout: (Component field) -> void
+
+      # Rewrites the half-typed shapes {NUMERIC} admits into ones every
+      # `bigdecimal` version parses: `".5"` → `"0.5"`, `"1."` → `"1"`.
+      # 
+      # _@param_ `text` — a buffer matching {NUMERIC}.
+      def normalize: (String text) -> String
+
+      # _@param_ `new_value`
+      def coerce: ((::BigDecimal | Integer | String) new_value) -> ::BigDecimal
+
+      # 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`
+      # 
+      # _@return_ — true to consume the key.
+      def field_key: (String key) -> bool
+
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as
+      # zero.
+      # 
+      # _@param_ `delta`
+      def step: (Integer delta) -> void
+
+      # 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` — a single printable character.
+      def accepts?: (String char) -> bool
+
+      # 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.
+      def fire_if_changed: () -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+    end
+
     # Abstract base for the **String-valued** editable text components
     # ({TextField}, {TextArea}): a field whose {HasValue#value} *is* its text.
     # A field whose value is a different type (an `Integer`, a domain object)
@@ -5209,11 +6053,20 @@ module Tuile
     # wrapped continuations, hard `"\n"` breaks preserved as separate output
     # lines.
     # 
+    # An indent is content, so it survives onto the first row — but there is no
+    # hanging indent:
+    # 
+    #   StyledString.plain("  read config").wrap(20).map(&:to_s)
+    #   # => ["  read config"]        indent kept; the line never wrapped
+    #   StyledString.plain("  read config").wrap(6).map(&:to_s)
+    #   # => ["  read", "config"]     ...but a continuation starts at column 0
+    # 
     # Whitespace runs are space or tab; other characters are treated as word
     # content. When a single character is wider than `width` (e.g. a 2-column
     # CJK character with `width = 1`), it is still emitted on its own line at
     # its natural width. The "no line exceeds `width`" guarantee therefore
-    # holds whenever every character is at most `width` columns wide.
+    # holds whenever every character is at most `width` columns wide. An indent
+    # that alone exceeds `width` is dropped rather than given a row of its own.
     # 
     # _@param_ `width` — target column width. `nil` or `<= 0` skips wrapping and returns each hard-line as-is, so callers can pass a stale viewport width without crashing.
     #