tuile 0.15.0 → 0.17.0

data/TERMINOLOGY.md

@@ -1,85 +0,0 @@
-# TERMINOLOGY.md
-
-Tuile's house vocabulary — one line per term, looked up by word.
-
-This file owns **definitions only**. The *rules that bite* live in AGENTS.md
-("Nomenclature" and the sections each word belongs to); the *why we chose a word
-and not its synonym* lives in DECISIONS.md (`D_scroll_nomenclature` for the
-row/line/item split); the *concepts* live in the book. When a definition here
-needs a paragraph of justification, that paragraph belongs in one of those three.
-
-## The grid
-
-| term | means |
-|---|---|
-| **row** | one row of the terminal grid — the framework's only word for it. A wrapped unit of text *is* a row; wrapping is what turns text into rows. |
-| **column** | one cell-column of the terminal grid; the unit `display_width` counts. |
-| **cell** | one grid position: a grapheme plus a {Tuile::StyledString::Style}, in {Tuile::Buffer}. |
-| **glyph** | what the terminal draws in one or more cells. Ambiguous-width glyphs count as **one** column (the bet in `D_ambiguous_width`). |
-| **cluster** | a grapheme cluster — the unit measurement, slicing, caret motion and deletion all work in. Never `each_char`. |
-| **row_in_viewport** | a row measured `0...rect.height`, i.e. relative to a component's own rect. |
-| **scroll_top_row** | the content row currently sitting at the top of the viewport. |
-| **left_column** | the content column currently painted in a widget's leftmost cell — the horizontal counterpart of `scroll_top_row`. Private wherever it exists (`TextField`, `Tabs`, `MenuBar`): what a caller relies on is the invariant it maintains — the caret, or the selected segment, is in view — not the number. |
-| **viewport_rows** | how many rows of content are visible — always `rect.height`; kept private, since `rect.height` is the public form. |
-| **row_count** | how many rows the wrapped content occupies. Public on `TextArea` (with `caret_row`, its companion); also on the private `WrappedText` and as `VerticalScrollBar.new(row_count:)`. Not on `TextView` / `List`, which have no caller for it. |
-| **caret_row** | the row a text input's caret sits in, counted from the content's first row. `TextArea` only. |
-| **extent** | the `Size` a widget actually paints inside the `rect` it was given — `Component#extent`, `nil` unless declared, always at the rect's top-left (`Component#extent_rect` positions it). What the widget clears outside of, hit-tests, highlights and anchors its dropdown to. The arithmetic is each widget's own (a `Checkbox`'s glyph plus caption; a `Tabs` strip's segments and separators). Distinct from a *slot extent*. |
-| **handle** | the moving part of a {Tuile::VerticalScrollBar} — the rows standing for the slice of content in view (`handle_start` … `handle_end`, `handle_char`). CSS calls it the *thumb*; Tuile does not. Not drawn at all when the content fits. |
-| **track** | the scrollbar's fixed part: the full viewport height the handle moves within, and the glyph (`track_char`) painted on the rows the handle doesn't cover. Never the bar's *column*, which is "the scrollbar column" (`D_scrollbar_reserve`). |
-| **segment** | one tab's span on a {Tuile::Component::Tabs} strip: its caption plus a padding column either side. The unit a click resolves to; the separator column between two segments belongs to neither. |
-
-**Space rule 1.** An object with only one row space leaves `row` unqualified:
-{Tuile::Buffer} *is* the grid, so its rows are screen rows;
-`TextArea::WrappedText` is content, so its rows are content rows.
-
-**Space rule 2.** A component holding both spaces qualifies the viewport one
-(`row_in_viewport`); its unqualified `row` and its `scroll_top_row` are
-content-space.
-
-## Text and content
-
-| term | means |
-|---|---|
-| **line** | a `\n`-delimited unit of a String — exactly what `String#lines` returns. **Never a coordinate.** |
-| **line_count** | a count of `\n` units (`TextView::Region#line_count`). Never a row count. |
-| **item** | a domain object a widget holds and renders — `List#items`, and the enum widgets above it. |
-| **renderer** | the `item -> row` proc a generic component uses to render an item it knows nothing about. |
-| **selection** | which item or tab a selector currently points at. *View state* when nothing would save it ({Tuile::Component::Tabs}`#selected`), a *value* when a form would (`RadioGroup#value`) — the split `D_tabs` calls the "would a form save it?" test. |
-| **item_count** / **item_index** | how a `List::Cursor` counts and addresses; equal to a row count in a `List`, but the cursor indexes *items*. |
-| **text** | the user-editable **value** of an input ({Tuile::Component::HasValue}, aliased as `text` on `AbstractStringField`). |
-| **caption** | app-authored **chrome** text ({Tuile::Component::HasCaption}) — a `Window` title, a `Button` label. Never a value. |
-| **chrome** | framework- or app-authored decoration around content: captions, borders, footers, an app's status line. |
-| **caret** | the index into an input's `text` where editing happens; always on a cluster boundary. Distinct from the *cursor*. |
-
-## Tree, paint and theme
-
-| term | means |
-|---|---|
-| **component** | a node of the UI tree ({Tuile::Component}); the only thing that paints. |
-| **slot extent** | in a `Layout::Box`, the size a parent *allocates* a child along an axis — what `Fixed` / `Percent` / `Expand` declare, and what `main_extent` / `cross_extent` measure. The parent's allocation, where a component's *extent* is the child's own painted region; `D_extent` turns on the two being different. Here `slot` is the box's allocation for one child and has **nothing** to do with {Tuile::Component::Slot} — the phrase is glossary-only (the code says `main_extent` / `cross_extent`), so read it as one term, never as "the extent of a `Slot`". |
-| **tile** / **tiled** | the non-popup part of the tree — `ScreenPane#content` and its descendants. Also *to tile*: to cover a rect completely. |
-| **attached** | reachable from a {Tuile::ScreenPane} via the parent chain — the one axis `attached?` consults. |
-| **wrapping field** | a field that owns and hides one *inner editor* and carries a typed value over it — {Tuile::Component::AbstractWrappingField} and its subclasses. The editor is private machinery: no public accessor, `children` the only way in. |
-| **inner editor** | the {Tuile::Component::AbstractStringField} a *wrapping field* wraps. Always this phrase — never "the wrapped field", which would name the wrong one of the two fields in play. |
-| **slot** | a named region of a container, reached by identity (`content`, `footer`) as well as through `children`. Two forms: a plain named child the caller populates directly (`HasContent#content`, the primary one); or a {Tuile::Component::Slot}, the one-child region component, wired once so its occupant may be absent or swapped (`Window#footer`). Capital-`S` `Slot` always means the class. |
-| **cascade** | the stack of open {Tuile::Component::ListDropdown} panels a {Tuile::Component::MenuBar} drives, one per level, the last deepest. Each is an overlay on the pane, not a child of the bar. |
-| **submenu** | a menu item that opens a further panel instead of doing something — `MenuBar::Item#submenu?`, true iff the item has children. Painted with a trailing `▸`. |
-| **mnemonic** | a letter that activates one {Tuile::Component::MenuBar} item, underlined in its caption. Always *level-scoped*: matched against the top-level items while the cascade is closed and the deepest open panel while it is open, never across the two. |
-| **strip** | the one-row {Tuile::Component::Tabs} component: captions, one selected, no content of its own. A {Tuile::Component::MenuBar} has one too — same word, and the same extent-based hit testing, deliberately not the same look. |
-| **tab** | a {Tuile::Component::Tabs::Tab} — a caption plus an identity, minted and owned by the strip. Not a component (it never paints itself) and not an *item* (it holds per-element state, and the set is never assigned whole). Say "a tab" and "the Tab key"; never let the two words touch. |
-| **pane** | the component a {Tuile::Component::TabSheet} shows for the selected tab. The unselected ones are *detached* — one of the two ways to take something off the screen, and the one that fires the lifecycle hooks. |
-| **hidden** | carrying `visible? == false` — the component's own flag. *Gone*, not merely unpainted: as if detached, but still in the tree, so no lifecycle hook fires. Says nothing about the ancestors. |
-| **shown** | reachable by the user: this component and every ancestor visible. The effective, ancestor-inclusive state, and always the walk's word (`on_shown_tree`, `Box#shown_children`) — there is deliberately no `shown?` reader. |
-| **invalidate** | record a component as needing repaint; the loop coalesces and repaints once per tick. |
-| **cursor** | *(two senses, both live)* the hardware terminal cursor (`Screen#cursor_position`), and a `List::Cursor` — the selection position within a list. |
-| **well** | the background an input paints over its whole extent (`Theme#input_bg_color` / `#active_bg_color`), declared as its `default_bg_color`. It terminates inheritance — an ancestor's tint doesn't reach it — but loses to a `bg_color` set on the input itself. Exactly one per widget: a composed field owns the well and marks the field it wraps `Component::BG_INHERIT`. |
-| **token** | a semantic colour name on {Tuile::Theme} — an accent, never a global fg/bg. |
-| **scheme** | `:dark` or `:light`; a {Tuile::ThemeDef} pairs one {Tuile::Theme} per scheme. |
-
-## Locale
-
-| term | means |
-|---|---|
-| **conventions** | the formatting facts a {Tuile::Locale} carries — how a value is *rendered and parsed* (date formats, calendar, month and weekday names, decimal separator). Deliberately the opposite pole from *prose*, which a `Locale` never holds. |
-| **prose** | wording: a message in one language, belonging to one component. Outside `Locale` by rule, and outside Tuile by default — the wording fork of `D_bad_input` is where a translated one arrives. |
-| **primary format** | `formats.first` of a date field or a {Tuile::Locale#date_formats} list — the one a value is *written* in, and the only one that must survive a `strftime`/`strptime` round-trip. The rest only ever parse. |

data/ideas/arrow-key-navigation.md

@@ -1,221 +0,0 @@
-# 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.
-- **{Tuile::Component::Tabs} already left the vertical axis free for this.**
-  The strip claims Left/Right and *declines* Up/Down specifically so that this
-  feature can move focus out of it vertically while Left/Right keep switching
-  tabs inside it (`D_tabs`). It composes for nothing: the strip declines, the
-  key bubbles, the navigating ancestor moves. That is also the shape to copy
-  for any future one-axis widget — claim one axis, leave the other.
-
-## 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?
-
-**Q12 — Down out of a `Tabs` strip: to the pane, or past the whole
-`TabSheet`?** The strip is a child of the sheet, not of the navigating layout,
-so "walk direct children" sees the *sheet* holding focus and would move to the
-sheet's next sibling — skipping the pane the user is looking at. Entering the
-pane is almost certainly what a user means by Down here. Options: let a
-`TabSheet` claim Down when focus is on its strip (a `handle_key` on the sheet,
-no framework change, but a second place that binds an arrow); or have the
-navigating walk descend into a child that holds focus deeper than its first
-tab stop. Interacts with Q1's placement question.
-
-**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/binder.md

@@ -1,177 +0,0 @@
-# A Binder for Tuile — the pattern to copy, and the vocabulary that comes with it
-
-**Status:** filed 2026-09-03 as a **placeholder plus a settled vocabulary**.
-Nothing is designed here and nothing is implemented; the forms layer is not
-started. Two things earn the file: (1) Vaadin's `Binder` is the pattern to
-copy, and it is worth writing down *which parts* before anyone improvises one,
-and (2) the four-layer terminology below was settled while designing
-`HasBadInput` and has nowhere else to live until a `D_` entry exists — it is
-the reason that channel is called `bad_input` and not `presentation_error`.
-
-`D_has_value` is the standing authority on what belongs above the field:
-"Model-mapping (presentation ⟷ domain) is left to a future forms/binder layer
-*above* the field, never baked into field state", and it parks converters,
-`read_only` and the required-indicator there too. Nothing here overrides that.
-
-## The terminology (settled — this is the file's real content)
-
-Four layers, and the two arrows that matter. A `Date`-valued field bound to
-`Person#birth_date`:
-
-| layer | example | who speaks it |
-|---|---|---|
-| **model** | `Person#birth_date` | Binder only |
-| **transformations** | `birth_year` + `birth_month` + `birth_day` → a `Date`; a `birth_date_iso_string` → a `Date` | Binder only |
-| **value** | the `Date`, or `nil` — `HasValue#value` | **both** — the shared layer, which is why `HasValue` is *the* seam |
-| **input** | the glyphs the user typed, a calendar click, a mask's partial fill: `"2020-05-01"`, `"xyz"` | the field owns it; the Binder must be able to *ask about* it |
-
-| arrow | word | note |
-|---|---|---|
-| input → value | **parse** | *partial* — it can fail, and that failure is **bad input** (`D_bad_input`) |
-| value → input | **format** | *total* — formatting a `Date` into glyphs cannot fail |
-| the parse/format pair, inside a field | the field's **converter** | already the house word (`D_integer_field`: "the converter stays private and hardcoded"; `DECISIONS.md:2010`: a `parse`/`format` hook pair *is* the converter strategy) |
-| model ⟷ value, in the Binder | a **transformation** / the Binder's converters | a *chain*, possibly several steps |
-
-Why these words and not Vaadin's, in three lines:
-
-- **`presentation` is unavailable.** Vaadin's `Converter<PRESENTATION, MODEL>`
-  uses it for the **value** layer — `convertToModel` "receives a value that
-  originates from the user", `convertToPresentation` one "that originates from
-  the business object" — so it never names the glyph layer at all, and
-  `D_has_value` already adopted the same axis in prose. `Date` is the tell: it
-  *is* "the presentation" in Binder-speak while saying nothing about
-  formatting.
-- **A pair cannot name a chain.** model→value may be several transformations
-  (an old schema splitting a date across three columns), so naming one arrow
-  after the endpoints of a different chain is what made this confusing.
-- **`input` had to be freed.** Tuile's rdoc used "an input" for the *widget*
-  (~40 real sites, plus `Theme#input_bg_color`). The rule going forward:
-  **"input" alone is what the user put in; the widget is always a `field`**,
-  never "an input" — Tuile already says `field` 188 times, and TERMINOLOGY
-  already calls that background a **well**, so the token name is grandfathered
-  legacy. The sweep is a standalone mechanical pass, deliberately not bundled
-  with an unimplemented design. Note ~30 further hits are the ordinary English
-  sense ("a renderer whose *inputs* changed", "both shorter and longer *inputs*
-  are bugs") and must **not** change.
-
-**Reserved:** `model`, `transformations` and `presentation` belong to the
-layers above `value`; `domain` is the word `D_has_value` uses for the topmost
-one. Don't spend them on a field-level concept. At graduation the layer words
-go to TERMINOLOGY.md (one line each, beside `text` and `caption`) and the
-choice to a `D_` entry — a nomenclature ruling in the `D_scroll_nomenclature`
-mould.
-
-## Why Vaadin's `Binder` is the pattern
-
-It is the only one of the surveyed toolkits that keeps *form validity* as a
-single source of truth without pushing rules into the widgets — which is
-exactly the split Tuile has already committed to — the field reports what its
-own parse could not represent and never judges (`D_bad_input`), and the verdict
-lives in a slot only an outside validator writes (`D_has_validation`). The parts
-worth copying, from v25.2:
-
-- **`forField(field).withValidator(pred, message).bind(getter, setter)`** — a
-  builder per binding, rules declared beside the binding and nowhere else;
-  `asRequired("msg")` as the shorthand.
-- **`withConverter`** for the model⟷value transformations, including a
-  conversion-error message, and chains where each step sees the previous
-  step's output.
-- **`readBean` / `writeBean` / `writeBeanIfValid`**, with a write that refuses
-  when anything is invalid.
-- **`isValid` / `hasChanges` / `validate` → `BinderValidationStatus`** as the
-  aggregate the app asks.
-- **`binding.validate()`** for cross-field revalidation ("cannot return before
-  departing"), driven from the other field's value-change listener.
-- **Escape hatches that exist for real reasons:** `setValidatorsDisabled`,
-  `setDefaultValidatorsEnabled(false)` / `withDefaultValidator(false)`, and
-  `setIsAppliedPredicate` for a binding that shouldn't participate at all.
-
-What Tuile should *not* copy: `HasValidator#getDefaultValidator` and
-`addValidationStatusChangeListener`. Both exist to repair a *shared*
-`invalid`/`errorMessage` cell on the component; Tuile puts the two facts in two
-places instead, so the repair has nothing to fix (`D_bad_input`, and
-`Component::HasValidation`, shipped 2026-09-03 — `D_has_validation`: one stored
-`error_message` the field never writes, so the Binder is its sole writer and
-sets-or-clears it on every validate pass). Ruby also deletes most of the
-ceremony: a validator is a proc returning a message or `nil`, so there is no
-`Validator` interface, no `ValidationResult`, and no `Result.ok`.
-
-## What the Binder must consume from a field
-
-- **`is_a?(HasValue)` is the marker** for "this is bindable" — `D_integer_field`
-  says so explicitly.
-- **`field.respond_to?(:bad_input?) && field.bad_input?`** is the bad-input
-  question — **this half exists today** (`D_bad_input`) — asked at bind, at
-  click, at write, and whenever a sibling forces a revalidation. The *capability* is a class fact and may be cached at bind
-  time; the *status* may never be cached.
-- **Bad input must block the write even for an optional field.** This is the
-  failure Vaadin names and the whole reason the channel exists — an optional
-  field means "may be empty", not "may be garbage". And it cannot be reached
-  through `empty?`, which reports `true` for a field full of glyphs the value
-  cannot represent.
-- **A push notice (`on_bad_input_change`) is deliberately *not* built** — it
-  is needed only by a consumer that must react *between* clicks, which a Binder
-  gated at the click is not (`D_bad_input`, `D_on_blur`).
-
-## The Tuile-specific part: gating Save
-
-**The gate goes at the click, not on the button's enabled state.** Save asks
-the Binder when pressed and, on "no", opens an alert naming the problems
-(`ConfirmWindow.alert` exists — `D_confirm_window`). Vaadin's idiom is the
-other one (v25.2 `flow/binding-data/components-binder-load.md`):
-
-```java
-binder.addStatusChangeListener(event -> {
-    saveButton.setEnabled(event.getBinder().hasChanges()
-                       && event.getBinder().isValid());
-});
-```
-
-Three reasons not to copy it, ascending:
-
-- **`Button` has no disabled state** — no `enabled` axis on `Component`, no
-  `:disabled` in `BG_STATES` (AGENTS.md is explicit that the key is absent
-  because the *state* is absent). The enabled design needs framework work
-  first; the click design needs none.
-- **A disabled control says nothing about why**, and a TUI has no channel to
-  explain it: no tooltip, and hover is not even received (mode 1000 is
-  press-only — `ideas/hover.md`).
-- **It removes the only *continuous* consumer of the bad-input signal**, so
-  nothing needs a settling policy: a Binder asked only at the click sees one
-  settled state, and the flicker `D_bad_input` describes never arises on this
-  side. (The *well* still owes one, now that it ORs `bad_input?` — that debt is
-  unassigned and belongs to the first continuous consumer, per
-  `D_has_validation`.)
-
-If a settling policy is ever wanted here anyway, copy Vaadin's display rule
-rather than inventing one: errors count only after the user has edited a field
-and submitted.
-
-## Open, and deliberately not designed here
-
-Where a rule's message is *stored* and *shown* is answered by
-`D_has_validation`: stored on the field as `HasValidation#error_message`, shown
-as the field's own red *well* plus text in whatever cells surround it (the
-layout's inline-right message is still unbuilt — `ideas/form-layout.md`). The
-Binder writes it, and does not hold a per-binding cell of its own. Two
-consequences for the port: the write is a plain `field.error_message = msg_or_nil`
-per pass, and the Binder must **subscribe nothing** to show it — but it does
-compete for the single `on_error_message_change` slot with a `FormLayout` and
-with the app, which that note flags. Whether Tuile grows a `Signal` type to
-mirror Vaadin 25's `validationStatusSignal()` is untouched — Tuile's listener
-idiom is a plain proc, and nothing has asked for more.
-
-## Related
-
-`D_bad_input` (the field-side channel this consumes, already shipped),
-`D_on_blur` (the commit point that shipped, and why the push notice stays
-deferred), `D_has_validation` (the
-verdict slot this Binder is the sole writer of; where a message lives and who
-paints it), `ideas/form-layout.md` (the unbuilt container that would paint it),
-`ideas/new-components.md` (Tier 2 Form Layout, Custom Field; infra items 2–3),
-`D_has_value` (the forms layer owns converters, `read_only`, the
-required-indicator; the typed-value survey), `D_integer_field` (the field's own
-converter stays private; `is_a?(HasValue)` is the Binder's marker),
-`D_scroll_nomenclature` (the nomenclature ruling this vocabulary copies),
-`D_confirm_window` (the alert the Save button opens), `D_status_bar` (why the
-framework places no error row).

data/ideas/composite-field.md

@@ -1,77 +0,0 @@
-# `CompositeField`: several fields behind one value
-
-**Status:** filed 2026-09-04, as what was left over when
-`Component::AbstractWrappingField` shipped and its note graduated — read
-`D_wrapping_field` first, this note assumes it. Nothing here is built, and it
-waits for a **real consumer**: the two questions it turns on have no answer
-that today's components would test.
-
-The shape: a `DateTimeField` over a `DateField` plus a `TimeField`, i.e. several
-fields arranged in a layout behind one typed value. `AbstractWrappingField` is
-deliberately *one editor, full stop*, and was built as the prototype this learns
-from.
-
-What is already known about its shape:
-
-- **A sibling of `AbstractWrappingField`, not a subclass of it.** That base's
-  whole value is that one child removes the layout and the ordering; inheriting
-  from it would put both back.
-- **No auto-discovery of the fields — ever.** A tree walk for "the fields inside
-  me" would descend *through* a wrapping field into the private editor it exists
-  to hide. Registration is explicit.
-- **`active=` already gives it the right commit semantics** — see
-  `D_wrapping_field`, where that seam is chosen partly *because* it survives
-  here: focus moving between two of a composite's own fields keeps the composite
-  active, so it does not spuriously commit. The one hard part it inherits solved.
-- **The abstract pair generalizes by pluralizing.** `value` / `value=` already
-  mean "read the value out of my field(s)" and "apply the value into my
-  field(s)"; a composite changes nothing else about that contract, which is the
-  evidence the prototype transfers.
-- **It cannot inherit the "the base adds the child" guarantee**, and that is
-  another reason it is a sibling. `AbstractWrappingField` calls `add_child`
-  itself, which is what makes *own and hide* a guarantee rather than a
-  convention. A composite must let its subclass populate a layout, so something
-  else has to replace it — explicit registration of which descendants are its
-  fields.
-- **What it must solve, and a wrapping field never had to:** assembling `value`
-  from several children with a diff guard; deciding whether `bad_input?` is "any
-  child" or "the combination"; which child takes focus on `on_focus`; and how
-  the layout is expressed without becoming a container.
-
-**The hard one: which component wears the error, and it is already half
-answered.** Picture `Date: [DateField] Time: [TimeField]` — a `Horizontal` of
-four children, two of them labels. Two strategies: the composite marks *itself*
-invalid, or it marks each of its *fields*. **They are not symmetric — the first
-is already broken by the background chain.** `error_bg_color` sits at the top of
-the same chain a child walks, so a child inherits its parent's *error* level,
-not merely its normal well. Verified:
-
-```ruby
-f = Component::IntegerField.new
-f.error_message = "nope"
-label_under_it.effective_bg_color   # => Color 88 — the error well
-```
-
-So a composite that marks itself reddens its `Date:` and `Time:` labels, which
-is wrong for the same reason `D_caption_ownership` keeps a caption off a field:
-that text is chrome, and chrome is not the thing that failed. That points at
-marking the fields — but it leaves the genuinely hard case open, and it is the
-case a composite exists for: a **combination** error (`start > end`) where no
-single field is wrong. Marking one is a lie, marking all of them is loud, and
-marking none loses the signal. Unsolved, and the reason the whole area waits for
-a real consumer.
-
-**BG_INHERIT is the same question wearing a different hat** — does a composite's
-whole subtree inherit its well (and the labels sit in it), or only the fields
-(and the layout's gaps show terminal default, looking patchy)? Both readings are
-defensible, neither has a consumer, so nothing guesses yet.
-
-## Related
-
-`D_wrapping_field` (the one-editor base this generalizes — its admission test,
-its forwarding test, and `active=` as the commit point), `D_has_validation` and
-`D_bad_input` (the two error channels a composite has to combine),
-`D_caption_ownership` (why an inner label is chrome, and chrome is not what
-failed), `D_bg_surface` (the background chain that makes "mark self" redden the
-labels), `D_date_field` (`DateTimeField` is the plausible first
-consumer).