tuile 0.14.0 → 0.16.0

data/TERMINOLOGY.md

@@ -1,71 +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*. |
-| **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. |
-| **slot** | a named region of a container, reached by identity (`content`, `footer`) as well as through `children`. Two forms: a plain named child, when the occupant is permanent and integral (`HasContent#content`); or a {Tuile::Component::Slot}, the one-child region component, when the 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*, which is how Tuile hides a component. |
-| **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 explicit background an input paints over its whole rect (`Theme#input_bg_color` / `#active_bg_color`), which opts it out of `bg_color` inheritance. |
-| **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. |

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/modal-backdrop.md

@@ -1,24 +0,0 @@
-# Modal backdrop — dim the content under a popup, or cast a shadow
-
-**Status:** seed, 2026-08-31. Deliberately not brainstormed yet; spun off from
-the `ConfirmWindow` design (`D_confirm_window`'s sizing paragraph).
-
-**The problem.** A modal `Popup` floats over the tiled content with no visual
-separation beyond its own border: the content underneath is neither dimmed nor
-shadowed. A small popup — a `ConfirmWindow` measuring a one-line "Overwrite?" —
-can sit in the middle of a busy screen and simply not be noticed.
-
-**The two candidate treatments** (every GUI stack ships at least one):
-
-- **Dim/tint** the non-popup cells under the topmost modal.
-- **A drop shadow** — a one-cell dark offset under/right of the popup box.
-
-**Hooks that exist today, for whoever picks this up:** `Screen#repaint`
-already partitions tiled vs. popup subtrees and repaints popups on top, so a
-dim pass has a natural slot between the two. Terminal cells are opaque
-(`D_bg_inherit`), so "dim" means restyling cells, not compositing — and
-`Color` has no darken/blend operation yet, which a dim factor would need.
-
-**Open when picked up:** flush-time transform in `Buffer` vs. repaint-time
-style override in components; does a shadow belong to `Overlay` or only
-`Popup`; interaction with themes and with the terminal-default (unset) bg.

data/ideas/new-components.md

@@ -1,124 +0,0 @@
-# Components Vaadin has and Tuile doesn't — the survey
-
-**Status:** survey done 2026-07-25 against Vaadin **25.2** (54 free/OSS
-components, via the Vaadin docs MCP). This file is the roadmap; each
-component we actually decide to build gets its own `ideas/<name>.md`.
-Retire this file once the interesting part of the list is either built or
-explicitly rejected — the tiering below is the only nugget worth keeping,
-and it belongs here, not in a durable doc, because it goes stale as we
-build.
-
-Batch 1 ("field components only") is **done** — every idea filed under it has
-graduated: `checkbox` (`DECISIONS.md` `D_boolean_fields`) and `checkbox-group`
-(`D_checkbox_group`), both built 2026-07-30; `radio-group` (`D_radio_group`),
-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,
-Integer Field, Combo Box (1:1), Dialog ({Tuile::Component::Popup} plus
-`Window`/`InfoWindow`/`PickerWindow`), Themable Mixin
-({Tuile::Theme}/{Tuile::ThemeDef}). **List Box** is half-there:
-{Tuile::Component::List} takes typed items and a renderer since 2026-08-14
-(`D_list_items`), but has no multi-select — {Tuile::Component::CheckboxGroup}
-is the nearest thing.
-
-Tuile also has pieces Vaadin doesn't name as components — `ListDropdown`,
-`TextView`, `LogWindow`, `VerticalScrollBar` — so the gap is not
-symmetric.
-
-That leaves ~46 gaps.
-
-## Tier 1 — reachable from what exists (S–M each)
-
-| Component | Builds on | Note |
-|---|---|---|
-| ~~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~~ | `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` | **built** 2026-08-17 (`D_notification`, book ch7); one non-modal top-right box, N messages, one 3 s ticker retiring the oldest. Corner anchor is its own `reposition` override, so `Popup` was untouched — and the `Popover` extraction still waits for a second *kind* of anchoring |
-| ~~Confirm Dialog~~ | `Popup`+`Window`+`Button` | **built** 2026-08-31 as `ConfirmWindow` (`D_confirm_window`, book ch7); the component is the builder — `#button` plus the `alert`/`confirm`/`yes_no` factories — every button dismisses, MenuBar-shaped mnemonics with `q`/`g`/`G` reserved. The fold-`PickerWindow`-in idea is **rejected**: the two disagree on every semantic that matters (cursor, default, ESC, close-on-pick) and share only API shape |
-| Details → Accordion | `HasContent` | Details is the atom, Accordion the group |
-| ~~Tabs → TabSheet~~ | plain `Component` + the tree API | **built** 2026-08-23 (`D_tabs`, book ch7); a strip (one tab stop, Left/Right, immediate activation) plus a sheet whose `children` are `[strip, pane]`. Neither is `HasValue` — a tab selection is view state — and neither is `HasContent`; hiding a pane means *detaching* it, since Tuile has no visibility flag; the strip owns mutable `Tabs::Tab` handles rather than the `items`/`item_label` shell. Hidden/disabled/closeable tabs, lazy panes and a scrolling strip are deferred, each additive (`D_tabs`) |
-| 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. Nothing gates on it today: Menu Bar shipped without it |
-| ~~Menu Bar~~ | `ListDropdown` (+ `anchor_beside`) | **built** 2026-08-24 (`D_menu_bar`, book ch7), mnemonics the same day. Turned out *not* to need the Popover extraction: a focused strip drives a cascade of non-modal `ListDropdown`s the way `Select` drives one, so the additions were a side-anchor method, a highlighted-row rect and a cursor pass-through. Unlimited submenu depth; checkable/disabled items and global-shortcut activation deferred indefinitely |
-| Slider | `draw_line` | arrows/PgUp; 25.2 also has a two-thumb *range* variant |
-| Breadcrumbs | `Label`/`StyledString` | clickable path segments |
-| Markdown | `TextView` + `StyledString` | Markdown subset → styled text; high value on a TTY |
-
-## Tier 2 — worth doing, each blocked on a new seam
-
-| Component | Blocked on |
-|---|---|
-| **Grid** (the flagship gap) | column model + renderer strategies + typed items + horizontal scroll (L) |
-| Form Layout | a field label/helper seam (Vaadin's `HasLabel`) — Tuile fields carry no caption |
-| Email Field | a validation seam (`HasValidation`: invalid state + error line) |
-| Date / Time / DateTime Picker | calendar-grid popup over Popover (L) |
-| Multi Select Combo Box | Checkbox Group + ComboBox |
-| Split Layout → Master Detail Layout | mouse **motion/drag**: Tuile runs X10 mode 1000 (press only, no release, no motion) |
-| Virtual List | a lazy data-provider strategy on `List` |
-| Side Nav | hierarchical collapsible list (the sampler's nav is the prototype) |
-| App Layout | shell: title bar + drawer + content slot |
-| Custom Field | formalize the composed typed-field pattern — or *reject* it as a shared base (COP: inherit to *be*, not to share); `D_integer_field` already sketches the taxonomy |
-| Message Input / Message List / Login | nothing — pure assemblies, good example fodder |
-| Upload | reinterpret as a file-chooser dialog (`file_commander` has the ingredients) |
-| Icon | a glyph / Nerd-Font constants module |
-
-## Tier 3 — design tension or marginal
-
-- **Scroller** — scrolling *arbitrary* content needs clipping/viewport
-  machinery and pushes against the top-down layout invariant (it wants to
-  measure content). Best kept as a documented road-not-taken.
-- **Tooltip** — competes with Tuile's status-bar `keyboard_hint` idiom.
-- **Card** — overlaps `Window` almost entirely.
-- **Avatar / Avatar Group** — initials in a box; little value on a TTY.
-- **Not applicable:** Field Highlighter (collaboration), Themable Mixin
-  (covered by `Theme`).
-
-## Infrastructure that gates clusters
-
-These are prerequisites, not components, and each deserves its own idea
-file when its cluster comes up:
-
-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** → pickers, Tooltip. **No longer gates Menu
-   Bar** — `D_menu_bar` argues the side-anchor is a sibling method on
-   `ListDropdown`, since both callers still wrap a `List`; the extraction's
-   trigger is now the first non-`List` content that wants anchoring.
-5. **Mouse motion/drag** (modes 1002/1006, release events) → Split
-   divider, Slider drag, scrollbar drag.
-6. **Typed items + data provider on `List`** → List Box, Grid, Virtual
-   List. **Half done** 2026-08-14 (`D_list_items`): `List` takes `items` +
-   a `renderer` and renders only the visible rows, and the five composers
-   are folded onto it. The remaining half is *sourcing* items lazily (a
-   data provider behind `items`), which lazy rendering was chosen to keep
-   reachable without a redesign.
-
-Vaadin's `Binder` is the natural companion for the forms cluster but is
-not a component; `D_has_value` already parks the forms-layer questions
-(converters, read-only, required indicator).
-
-## ~~Cross-cutting open question: component color slots vs. theme tokens~~
-
-**Settled 2026-08-01 as `DECISIONS.md` `D_color_slots`** — the slot, defaulting
-to `nil`. Slider and Badge are bound by it when they land; Badge's promotion
-trigger (a *second* built-in needing the same semantic color) is written up
-there, so neither has to re-argue it.

data/ideas/per-component-buffers.md

@@ -1,55 +0,0 @@
-# Per-component back buffers + a z-order compositor
-
-**Status:** deferred, not worth doing yet. Graduated out of `Buffer`'s
-rdoc (it was speculative design musing, not caller contract — see the
-doc-kinds rules in AGENTS.md). Parked here so the thinking isn't lost.
-
-## The idea
-
-Today there is one global {Tuile::Buffer}: every component paints into
-the same grid via `set_line` / `set_char` / `fill`, and {Tuile::Screen}
-flushes its minimal diff to the terminal.
-
-Components already paint through that drawing surface *without knowing*
-whether it's the one global buffer or a private one — the indirection is
-deliberate. So per-component back buffers plus a z-order compositor could
-drop in **without touching component code**: give each component its own
-`Buffer`, let it paint into that, and have a compositor blend the
-per-component buffers in stacking order into the frame the terminal sees.
-
-## Why it's not worth doing yet
-
-The current single-buffer diff already captures most of the win a
-compositor would give:
-
-- The flush drops unchanged cells from the wire, so an unchanged region
-  costs nothing on the terminal side regardless of how many components
-  overlap it.
-- An occluded component that didn't change is never repainted at all —
-  invalidation gates it out before `repaint` runs.
-
-So a compositor would only save **residual `repaint` CPU**: the cost of a
-component re-rendering its content into a buffer, when that content then
-turns out to be occluded or unchanged after compositing.
-
-## The one regime where it pays off
-
-High repeat-rate scroll — a held arrow key or a spun mouse wheel — over a
-**large** component on a **large** screen, where re-rendering the
-component's content on every repeat is the dominant cost. A per-component
-buffer would let an unchanged-but-scrolled component be re-composited
-(cheap) instead of re-rendered (expensive) each repeat.
-
-Until Tuile has a real workload in that regime, the extra machinery
-(per-component buffer allocation, a compositor pass, dirty propagation
-across buffer layers) buys nothing over what the single-buffer diff
-already delivers.
-
-## If we revisit
-
-- The component-facing drawing API (`set_line` / `set_char` / `fill`)
-  stays the same — that's the whole point of the existing indirection.
-- What changes is *who owns the buffer* and the addition of a
-  composite-into-frame step between `repaint` and `Buffer#flush`.
-- Measure first: prove the residual-`repaint`-CPU regime is real and
-  material before adding a layer.

data/lib/tuile/mouse_event.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module Tuile
-  # A mouse event.
-  #
-  # @!attribute [r] button
-  #   @return [Symbol, nil] one of `:left`, `:middle`, `:right`, `:scroll_up`,
-  #     `:scroll_down`, `:scroll_left`, `:scroll_right`; `nil` if not known.
-  # @!attribute [r] x
-  #   @return [Integer] x coordinate, 0-based.
-  # @!attribute [r] y
-  #   @return [Integer] y coordinate, 0-based.
-  class MouseEvent < Data.define(:button, :x, :y)
-    # @return [Point] the event's position.
-    def point = Point.new(x, y)
-
-    # Checks whether given key is a mouse event key. Returns true on the X10
-    # `\e[M` prefix regardless of length — {.parse} is the place that
-    # validates the full 6-byte shape and raises on malformed input.
-    # @param key [String] key read via {Keys.getkey}
-    # @return [Boolean] true if it is a mouse event
-    def self.mouse_event?(key)
-      key.start_with?("\e[M")
-    end
-
-    # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y).
-    #
-    # Raises {Tuile::Error} when `key` starts with the mouse prefix but is
-    # not exactly 6 bytes long. Both shorter and longer inputs are bugs in
-    # the upstream key-reader: a shorter prefix means the tail was lost on
-    # the way in, and a longer one means we over-consumed into the next
-    # escape sequence. We refuse to silently truncate either case because
-    # the trailing `\e` of an over-read corrupts the *next* getkey, and the
-    # corruption then surfaces as garbled keystrokes in focused inputs
-    # rather than as a parser failure pointing at the actual cause.
-    # @param key [String] key read via {Keys.getkey}
-    # @return [MouseEvent, nil] `nil` if `key` is not a mouse event
-    # @raise [Tuile::Error] if `key` is a malformed mouse event
-    def self.parse(key)
-      return nil unless mouse_event?(key)
-      unless key.bytesize == 6
-        raise Tuile::Error,
-              "malformed mouse event: expected 6 bytes after \\e[M prefix, got #{key.bytesize}: #{key.inspect}"
-      end
-
-      button = key[3].ord - 32
-      # XTerm reports coordinates 1-based (column N is encoded as N + 32);
-      # subtract 33 so that `x` and `y` are 0-based.
-      x = key[4].ord - 33
-      y = key[5].ord - 33
-      button = case button
-               when 0 then :left
-               when 2 then :right
-               when 1 then :middle
-               when 64 then :scroll_up
-               when 65 then :scroll_down
-               when 66 then :scroll_left
-               when 67 then :scroll_right
-               end
-      MouseEvent.new(button, x, y)
-    end
-
-    # @return [String]
-    def self.start_tracking = "\e[?1000h"
-    # @return [String]
-    def self.stop_tracking = "\e[?1000l"
-  end
-end