tuile 0.12.0 → 0.13.0

data/README.md

@@ -57,11 +57,10 @@ else in Tuile loads it.
 
 ## Documentation
 
-- **[The Tuile guide](book/README.md)** teaches Tuile cover to cover — the
-  component tree, the top-down layout model and the case for why it's
-  enough, the single-threaded event loop and background work, focus, and
-  theming. Start here to learn the concepts and the *why*. It grows a
-  chapter at a time; the layout chapter is the heart of the design.
+- **[The Tuile guide](book/README.md)** teaches Tuile cover to cover, in
+  order — the concepts and the *why*. Start here; the summary below links
+  into it chapter by chapter, and the layout chapter is the heart of the
+  design.
 - **API reference:** every public class and method carries YARD headers —
   browse them at <https://rubydoc.info/gems/tuile>, or run
   `bundle exec rake yard` for a local site.
@@ -101,494 +100,141 @@ Shift+Tab move focus between the list and the demo's widgets.
 
 ## How it works
 
-### Component tree
-
-Everything on screen is a `Tuile::Component`. Components have a `parent`,
-`children`, a `rect` (absolute position), and an `active?` flag (true for
-every component on the focus chain root → focused).
-
-A single `Tuile::Screen` (process singleton) owns the tree. Under it sits a
-structural `ScreenPane` with three slots: tiled `content` (your app's main
-layout), a `popups` stack (modal overlays), and a one-row `status_bar`.
-Putting popups under the same parent as content means focus traversal,
-attachment checks and child-removed callbacks all work uniformly.
-
-### Layout and repaint
-
-Repainting has two halves: an *invalidation* pass decides which components
-re-render, and a *back buffer* turns their output into the minimal set of
-bytes sent to the terminal. There is no clipping in between.
-
-1. A component that needs to redraw calls `invalidate`. This just records the
-   component in a set on the screen.
-2. After the event loop drains the current batch of keyboard/mouse/posted
-   events, the screen runs a single `repaint` pass:
-   - Invalidated **tiled** components are sorted by tree depth (parents first)
-     and each one repaints its `rect`.
-   - If anything tiled was redrawn, **all popups** are drawn on top in
-     stacking order. Popups deliberately overdraw content; there is no
-     clipping — overdraw is free because it only touches the buffer.
-   - The hardware cursor is moved to the focused component's
-     `cursor_position` (e.g. into a focused text field).
-
-Components never write escape sequences to the terminal. They paint styled
-cells into a back buffer (`Tuile::Buffer`) via `set_text` / `fill` /
-`set_char`. When the pass finishes, `Buffer#flush` emits the **minimal diff**
-— only the cells that actually changed since the last flush — wrapped in one
-synchronized-output batch. That is what keeps repaint flicker-free on any
-terminal regardless of mode-2026 support: an unchanged cell is never
-rewritten, so a popup overdrawing content costs nothing on the wire unless it
-changes a visible cell.
-
-A component must fully cover its own `rect`, but it need not tile that rect
-with children: the default `repaint` clears the background behind any gaps and
-re-invalidates its children to paint on top, so a layout with mixed-width
-fields shows no stale characters. Components that paint their entire rect
-themselves (`Window`, `List`) opt out of that default. `Layout` paints nothing
-of its own and positions its children within its rect.
-
-### Single-threaded event loop
-
-`Tuile::Screen#run_event_loop` reads keys and mouse events on a worker thread,
-funnels them through `Tuile::EventQueue`, and processes them on the main
-thread. **All** UI mutations — `rect=`, `content=`, `items=`, `invalidate`,
-`screen.focused=` — must run on that thread. Most UI methods will raise
-`"UI lock not held"` if you violate this.
-
-If you need to mutate the UI from a background thread (an HTTP poll, a file
-watcher, a worker), marshal the work back via the queue:
-
-```ruby
-Thread.new do
-  result = some_long_call
-  screen.event_queue.submit { log_window.content.add_line(result) }
-end
-```
-
-`SIGWINCH` (terminal resize) is plumbed through the same queue: the framework
-posts a size event, runs layout, and invalidates the entire tree. Components
-react by reassigning their child rectangles inside `rect=` — do not install
-your own WINCH handler.
-
-### Focus and keyboard input
-
-`screen.focused = component` walks parent pointers up to the root, marks the
-whole chain `active?`, and deactivates everything else. Click-to-focus and
-`Layout#on_focus` only ever forward focus to components whose `focusable?`
-returns true, so clicking a `Label` inside a `Window` does not pull focus
-away from the window's content.
-
-When a key arrives, the screen dispatches it in this order — the first
-mechanism that handles it wins:
-
-1. **Tab / Shift+Tab** advance focus through `tab_stop?` components in the
-   current modal scope (the topmost popup if one is open, otherwise the
-   tiled content). They are intercepted at the screen level before anything
-   else sees them, so a focused `TextField` cannot swallow them.
-
-2. **Global shortcuts** registered via `Screen#register_global_shortcut`.
-   These are app-level hotkeys for actions that don't belong to any
-   specific component — opening a log window, toggling help, etc.:
-
-   ```ruby
-   screen.register_global_shortcut(Tuile::Keys::CTRL_L,
-                                   over_popups: true,
-                                   hint: "^L #{screen.theme.hint('log')}") do
-     log_popup.open
-   end
-   screen.unregister_global_shortcut(Tuile::Keys::CTRL_L)
-   ```
-
-   This registry sits above the component tree and nothing suppresses it,
-   so it only accepts keys no widget can need: printable keys raise (they'd
-   hijack typing), as do Tab/Shift+Tab and `Screen::EDITING_KEYS` (Enter,
-   Backspace, Delete, the arrows). Control characters, ESC, `PgUp`/`PgDn`
-   and F-keys are yours. By default, the shortcut is suppressed while any
-   popup is open and the popup receives the key; pass `over_popups: true`
-   to pre-empt the popup.
-
-   Pass `hint:` to surface the shortcut in the status bar. It's a
-   preformatted string the caller fully owns (color it however the rest
-   of your app does). In the tiled case it appears right after `q quit`
-   and before the active window's hint; while a popup is open, only
-   `over_popups: true` hints show up, prepended before the popup's
-   `q Close`. Omit `hint:` to leave the shortcut silent in the status bar.
-
-3. **`Component#handle_key`** — override this on your own component when
-   it needs to react to keys directly (a list reacting to arrows, a custom
-   widget handling Enter, …). Return `true` to mark the key handled,
-   `false` to let the key keep travelling:
-
-   ```ruby
-   class Toggle < Tuile::Component
-     def handle_key(key)
-       if key == " "
-         @on = !@on
-         invalidate
-         true
-       else
-         false
-       end
-     end
-   end
-   ```
-
-   The key goes to the focused component first, then **bubbles up its
-   ancestors** to the scope root (the topmost popup, or the tiled content).
-   That makes an ancestor the right home for scope-wide keys — a form's
-   default button, or one-key jumps between panes — and it needs no special
-   protection, because a focused `TextField` consumes the key before the
-   ancestor ever sees it:
-
-   ```ruby
-   class AppLayout < Tuile::Component::Layout::Absolute
-     def handle_key(key)
-       case key
-       when "1" then @files.focus; true
-       when "2" then @log.focus; true
-       else false
-       end
-     end
-   end
-   ```
-
-If nothing handles the key and it's `q` or `ESC`, the event loop exits.
-
-A component can advertise the keys it responds to by overriding
-`keyboard_hint`. The status bar shows the active window's hint alongside
-the global `q quit` prompt; while a popup is open, the popup's own hint
-replaces it, prefixed with `q Close`:
-
-```ruby
-class FilterWindow < Tuile::Component::Window
-  def keyboard_hint
-    "f #{screen.theme.hint('filter')}  Enter #{screen.theme.hint('open')}"
-  end
-end
-```
-
-### Theming
-
-The accent colors built-in components paint with — the list-cursor /
-focused-input highlight, the inactive input "well", the active window
-border, the status-bar hint color — come from a `Tuile::Theme`, a frozen
-value type of semantic color tokens. The current theme lives at
-`screen.theme`.
-
-The theme is picked automatically when the screen is constructed:
-`Screen.new` queries the terminal's background color (OSC 11, with a
-`COLORFGBG` fallback) and selects `Theme::LIGHT` on light backgrounds,
-`Theme::DARK` (the colors Tuile has always used) otherwise. While the
-event loop runs, terminals supporting mode 2031 (kitty, foot, contour,
-ghostty, …) push appearance changes, and the screen follows OS
-light/dark flips live, repainting everything in the matching theme.
-Override it any time:
-
-```ruby
-screen.theme = Tuile::Theme::LIGHT
-# or tweak a single token (tokens are strict: `Color` instances only):
-screen.theme = Tuile::Theme::DARK.with(active_border_color: Tuile::Color::CYAN)
-```
-
-Note a bare `theme=` assignment is transient: the next OS appearance flip
-re-picks from the screen's `ThemeDef` and replaces it. To theme an app
-durably, see [App themes](#app-themes) below.
-
-The theme's primary API is its rendering helpers — `active_bg(text)`,
-`active_border(text)`, `input_bg(text)`, `hint(text)` — which return the
-text wrapped in the token's color:
-
-```ruby
-screen.theme.hint("quit")        # => "\e[38;5;109mquit\e[0m"
-screen.theme.active_bg("[ Ok ]") # => "\e[48;5;59m[ Ok ]\e[0m"
-```
-
-The raw colors are also readable via the `*_color` counterparts
-(`active_bg_color`, …) for span-aware styling with `StyledString`.
-
-Assigning a theme invalidates every component, so the whole UI restyles on
-the next repaint. One caveat: strings with colors already baked in (global
-shortcut `hint:`s, `Theme#hint` output you cached) don't restyle —
-rebuild them in `Component#on_theme_changed` (see
-[Reacting to theme changes](#reacting-to-theme-changes)).
-
-Everything that isn't an accent deliberately inherits the terminal's own
-default foreground/background, which already matches the user's terminal
-theme — so there is no global `bg`/`fg` token to configure.
-
-### App themes
-
-Your app's own colors belong in the theme too, so they restyle in the same
-invalidate-everything pass and stay legible on both terminal backgrounds.
-Beyond the built-in tokens, a theme carries app-specific tokens in
-`custom` — a `Hash{Symbol => Color}`. Look them up with `theme[:token]`
-(fail-fast: a typo raises `KeyError` instead of quietly painting a
-default) and render with the generic `fg` / `bg` helpers:
-
-```ruby
-theme = Tuile::Theme::DARK.with(custom: { accent: Tuile::Color::DARK_ORANGE })
-theme[:accent]             # => Color — e.g. for StyledString#with_fg
-theme.fg(:accent, "NEW")   # => "\e[38;5;208mNEW\e[0m"
-```
-
-`Color::DARK_ORANGE` is `Color.palette(208)` — the 256-color palette
-carries a constant per standard xterm chart name (`CADET_BLUE`,
-`DODGER_BLUE1`, `GREY37`, …; see `Color::PALETTE_NAMES`), so a theme
-declaration can say which color it means instead of citing a bare index.
-
-The recommended shape is a `Theme` subclass that implements one coloring
-function per custom token, mirroring the built-in helpers (`hint`,
-`active_bg`, …) — call sites then read `theme.added("+42")` instead of
-`theme.fg(:added, "+42")`. `Data#with` preserves the subclass, so an
-`AppTheme` stays an `AppTheme` through `with`:
-
-```ruby
-class AppTheme < Tuile::Theme
-  # one coloring function per custom token
-  def added(text)   = fg(:added, text)
-  def removed(text) = fg(:removed, text)
-end
-```
-
-Build both appearance variants and pair them in a `Tuile::ThemeDef`
-assigned to `screen.theme_def=`. This is the durable way to theme an app:
-the screen picks the member matching the detected background at startup
-and re-picks on every OS appearance flip, so your definition survives
-light/dark toggles where a bare `theme=` assignment would be replaced.
-`ThemeDef.new` enforces that both members declare the same custom key
-set — a token present in only one variant fails at construction instead
-of raising `KeyError` at the unpredictable moment the user flips
-appearance:
-
-```ruby
-APP_THEME = Tuile::ThemeDef.new(
-  dark:  AppTheme.new(**Tuile::Theme::DARK.to_h,
-                      custom: { added:   Tuile::Color::DARK_SEA_GREEN,
-                                removed: Tuile::Color::LIGHT_PINK3 }),
-  light: AppTheme.new(**Tuile::Theme::LIGHT.to_h,
-                      custom: { added:   Tuile::Color::SPRING_GREEN4,
-                                removed: Tuile::Color::INDIAN_RED })
-)
-screen.theme_def = APP_THEME
-```
-
-In tests, a fresh `Screen.fake` per example starts from the built-in
-definition, so a component reading `theme[:added]` would `KeyError`.
-Instead of repeating `Screen.instance.theme_def = APP_THEME` in every
-`before` block, point the construction-time default at your definition
-once, in `spec_helper.rb`:
-
-```ruby
-Tuile::ThemeDef.default = APP_THEME   # every Screen.fake now carries it
-```
-
-### Reacting to theme changes
-
-Built-in components read `screen.theme` at paint time, so their accents
-restyle automatically. Content you rendered yourself does not: a
-`StyledString` stored in `Label#text` / `List#lines=` / `TextView#text`
-has its colors baked in at construction, and only your app knows which of
-those were theme-derived (as opposed to inherent to the data — log-level
-colors, say). `Component#on_theme_changed` fires on every attached
-component when the theme changes (assignment or appearance flip); rebuild
-theme-derived content there by re-running the code that rendered it
-initially. Consume it either way:
-
-```ruby
-# composition style — assembling stock components:
-label.on_theme_changed = -> { label.text = render_status_line }
-
-# subclass style — call `super` so an assigned listener keeps firing:
-class DiffView < Tuile::Component::TextView
-  def on_theme_changed
-    super
-    self.text = render_diff   # screen.theme already returns the new theme
-  end
-end
-```
-
-The hook runs on the UI thread and repaint coalesces per tick, so
-mutating content inside it is safe. Don't assign `screen.theme=` from
-inside the hook.
+**A retained tree, not a redraw loop.** Everything on screen is a
+`Tuile::Component` with a `parent`, `children` and a `rect`. A singleton
+`Tuile::Screen` owns the tree; under it a `ScreenPane` holds the tiled
+content and a stack of popups. You build the tree once and mutate it —
+there is no per-frame rebuild and no immediate-mode redraw. Tuile paints no
+chrome of its own and reserves no row: your content gets the whole
+terminal, and a status line is yours to build if you want one.
+→ [chapter 1](book/01-first-app.md)
+
+**Repaint is automatic, and flicker-free without trying.** Components never
+write escape sequences. They call `invalidate`, and paint styled cells into a
+back buffer when the loop asks them to; one flush per tick emits the
+**minimal diff** — only the cells that actually changed — inside a
+synchronized-output batch. There is no damage tracking to maintain and no
+clipping to think about: popups simply overdraw, because overdraw into a
+buffer is free. → [chapter 2](book/02-repaint.md)
+
+**Layout is top-down, and that is the whole model.** A parent computes its
+children's rectangles in plain Ruby and assigns them; a component never
+advertises a size it would like. No `min`/`preferred`/`max`, no negotiation
+pass, no shrink-to-fit. Subclass `Layout::Absolute` when the arithmetic is
+yours, or use `Layout::Vertical` / `Layout::Horizontal` to declare each
+child's extent as `Fixed` / `Percent` / `Expand`.
+→ [chapter 3](book/03-layout.md)
+
+**One thread owns the UI.** Keys and mouse are read on a worker thread but
+dispatched on the loop's, and *every* UI mutation must happen there —
+violating it raises `Tuile::Error` rather than corrupting the screen.
+Background work marshals back through `screen.event_queue.submit { … }`, and
+periodic work through `tick` / `tick_fps`. Resize isn't a callback either:
+`SIGWINCH` becomes an event in the same queue.
+→ [chapter 4](book/04-event-loop.md)
+
+**Keys are routed by focus, in three rungs.** Tab and Shift+Tab are claimed
+above everything, so focus can never be trapped inside a widget; then an
+app-level registry (`Screen#register_global_shortcut`, which refuses keys a
+widget might need, printables included); then delivery to the focused
+component, bubbling up its ancestors to the scope root — which is what makes
+an ancestor the natural home for a form's Enter or a layout's one-key jumps
+between panes. A paste is deliberately *not* a burst of keys: with bracketed
+paste it arrives whole, as one `handle_paste`.
+→ [chapter 5](book/05-focus.md)
+
+**Theming is accents-only, and follows the OS.** A `Theme` carries semantic
+accent tokens — the list cursor, an input well, an active window border,
+status-bar hints — plus whatever `custom` tokens your app adds. Everything
+else inherits the terminal's own foreground and background, so Tuile looks at
+home in the user's palette instead of fighting it. Tuile probes the terminal
+background at startup, pairs a dark and a light theme in a `ThemeDef`, and
+re-picks on a live OS appearance flip.
+→ [chapter 6](book/06-theming.md)
 
 ## Components
 
-All components live under `Tuile::Component::*`. Each one is documented below
-with the methods you are most likely to reach for; full API docs are in the
-YARD output (`bundle exec rake yard`).
-
-### `Component::Label`
-
-Static text. No word-wrapping; long lines are clipped to `rect.width`. Lines
-may contain ANSI SGR formatting — theme helper output, a `StyledString`,
-or any SGR-emitting library (e.g. Rainbow, which is no longer a Tuile
-dependency — add it to your own Gemfile if you use it).
-
-```ruby
-label = Tuile::Component::Label.new
-label.text = "Hello, #{screen.theme.hint('world')}!"
-```
-
-Key API: `text=`, `bg=`.
-
-### `Component::Layout`
-
-Positions children but paints nothing of its own — children must completely
-cover the layout's `rect`. Use `add(child)` and `remove(child)`. By default,
-focus forwards to the first focusable child.
-
-```ruby
-class Header < Tuile::Component::Layout::Absolute
-  def initialize
-    super
-    @left = Tuile::Component::Label.new
-    @right = Tuile::Component::Label.new
-    add(@left)
-    add(@right)
-  end
-
-  def rect=(new_rect)
-    super
-    @left.rect  = Tuile::Rect.new(rect.left, rect.top, rect.width / 2, 1)
-    @right.rect = Tuile::Rect.new(rect.left + rect.width / 2, rect.top,
-                                  rect.width - rect.width / 2, 1)
-  end
-end
-```
-
-`Layout::Absolute` is the recommended base when you want to position children
-manually; it inherits all the focus / key dispatch wiring and only asks you
-to override `rect=` to reposition children whenever the parent resizes.
-
-### `Component::Window`
-
-A bordered frame with a caption and a single content slot. Optionally has a
-`footer` (a component that overlays the bottom border row, e.g. a search
-field) and a built-in scrollbar when the content is a `List`.
-
-```ruby
-window = Tuile::Component::Window.new("Settings")
-window.content = some_list
-window.scrollbar = true       # only valid when content is a Component::List
-window.footer    = search_field
-```
-
-Key API: `content=`, `footer=`, `caption=`, `scrollbar=`. Windows are
-focusable; focus delegates to content (or footer when active).
-
-### `Component::List`
-
-A scrollable list of items — one row each, rendered by a `renderer` — with
-optional cursor and scrollbar. `lines=` is the shortcut for items that are
-their own rendering.
-
-```ruby
-list = Tuile::Component::List.new
-list.lines = ["alpha", "beta", "gamma"]
-list.cursor = Tuile::Component::List::Cursor.new
-list.on_item_chosen = ->(index, item) { Tuile.logger.info("picked #{item}") }
-list.auto_scroll = true       # auto-scroll to bottom as the list grows
-list.lines = list.items + ["delta"]   # no appenders: assign the items whole
-```
-
-Cursor variants:
-
-- `List::Cursor::None` — no cursor (default).
-- `List::Cursor` — lands on every line; arrows / `jk` / Home / End / Ctrl+U /
-  Ctrl+D move it.
-- `List::Cursor::Limited` — restricts the cursor to a fixed set of line
-  positions (useful for menus where only some rows are selectable).
-
-Pressing Enter or left-clicking an item fires `on_item_chosen(index, line)`.
-
-Key API: `items=`, `renderer=`, `lines=`, `build_lines`, `cursor=`,
-`scroll_top_row=`, `auto_scroll=`, `scrollbar_visibility=`, `on_item_chosen`,
-`select_next` / `select_prev` (search).
-
-### `Component::TextField`
-
-A single-line input with a real terminal caret. The field does not scroll —
-keystrokes that would overflow `rect.width - 1` are rejected.
-
-```ruby
-field = Tuile::Component::TextField.new
-field.text       = "initial"
-field.on_change  = ->(text)  { filter_results(text) }
-field.on_enter   = ->         { submit(field.text) }
-field.on_escape  = ->         { popup.close }
-field.on_key_up  = ->         { results.cursor.go_up_by(1) }
-```
-
-Optional callbacks: `on_change`, `on_enter`, `on_escape`, `on_key_up`,
-`on_key_down`. When set, the corresponding key is consumed by the field; when
-nil, the key falls through to the parent (e.g. ESC closes the surrounding
-popup by default).
-
-### `Component::Popup`
-
-A modal overlay. It paints nothing itself: it wraps any component as
-`content`, sizes itself top-down from `size:` (a `Size`, or a `Fraction` of
-the screen resolved every layout pass — default `Fraction::HALF`), centres
-itself, and consumes `q` / `ESC` to close. The content fills that box and
-scrolls/wraps within it; it does *not* drive the popup's size. Popups are
-drawn on top of the tiled content; multiple popups stack.
-
-```ruby
-window = Tuile::Component::Window.new("Help")
-window.content = help_list
-popup = Tuile::Component::Popup.new(content: window, size: Tuile::Fraction::HALF).open
-# popup.close, popup.open?
-```
-
-Bare content also works (a `Label`, a `List`…) and yields a borderless popup;
-wrap in a `Window` if you want a frame. Pass `modal: false` for a non-modal
-overlay that floats above the content without grabbing focus — the caller
-positions and drives it.
-
-### `Component::InfoWindow`
-
-A `Window` preconfigured with a `List` of static lines. Convenient for
-read-only information.
-
-```ruby
-Tuile::Component::InfoWindow.open("Cannot open", [path, error.message])
-```
-
-Usable tiled too — just `add` it to a layout.
-
-### `Component::PickerWindow`
-
-A `Window` that lists single-keystroke options and fires a callback when one
-is picked. ESC / `q` cancel without firing.
-
-```ruby
-Tuile::Component::PickerWindow.open("Choose action", [
-  ["e", "Edit"],
-  ["d", "Delete"],
-  ["c", "Copy"]
-]) do |key|
-  perform(key)
-end
-```
-
-The callback receives the picked option's key. The popup variant closes
-itself after the pick.
-
-### `Component::LogWindow`
-
-A `Window` whose content is an auto-scrolling `List`. Wire your logger at it
-through `LogWindow::IO`:
-
-```ruby
-log_window = Tuile::Component::LogWindow.new("Log")
-Tuile.logger = Logger.new(Tuile::Component::LogWindow::IO.new(log_window))
-Tuile.logger.info("started up")
-```
-
-`LogWindow::IO` implements both `write` (stdlib `Logger`) and `puts`
-(`TTY::Logger` and similar), and marshals lines back through the event queue,
-so it is safe to log from any thread. Tuile itself is silent unless the host
-app sets `Tuile.logger`.
+Every component lives under `Tuile::Component::*`, and every one of them is a
+`Tuile::Component`: its parent sizes it top-down, it invalidates rather than
+paints, and it draws its accents from the theme. This is the catalogue — one
+line each, so you can find the right name. The **book** explains when and why
+to reach for each (chapter 7 is a tour organized by the job), and the **rdoc**
+carries the per-method reference: `bundle exec rake yard`, or
+<https://rubydoc.info/gems/tuile>.
+
+### Laying out — [book ch3](book/03-layout.md)
+
+| component | what it is |
+|---|---|
+| `Layout::Absolute` | Positions children by assigning their `rect` in a `rect=` override, and paints nothing itself. The base to subclass when the arithmetic is yours. |
+| `Layout::Vertical`, `Layout::Horizontal` | Stack children along one axis from declared extents — `Fixed[n]`, `Percent[n]`, `Expand[weight]` — with box-global `spacing` and `padding`. Sugar over `Absolute`, not a new sizing model. |
+
+### Framing and switching — [book ch7](book/07-components.md#framing-content)
+
+| component | what it is |
+|---|---|
+| `Window` | A frame with a `caption`, one content slot, and a border that lights up while the window is on the focus chain. `footer_text=` decorates the bottom border; `footer=` mounts a real component in it; `scrollbar=` reclaims the right border column. |
+| `MenuBar` | A one-row strip of menu captions, each dropping a cascade of submenus that nests without limit. Items are handles from `#add_item`, each with its own `on_click`. See [Menus](book/07-components.md#menus). |
+| `Tabs` | A one-row strip of captions with one selected, Left/Right switching immediately. Knows nothing about content — pair it with `TabSheet`, or drive your own view swap from `on_tab_selected`. |
+| `TabSheet` | A `Tabs` strip plus the pane belonging to the selected tab. Unselected panes are *detached*, so they keep their state and stay out of the Tab cycle. See [Switching between views](book/07-components.md#switching-between-views). |
+
+### Showing text — [book ch7](book/07-components.md#showing-text)
+
+| component | what it is |
+|---|---|
+| `Label` | Static text, one row per line, no wrapping — long lines are ellipsized. Content is a `StyledString`, so ANSI passes through. |
+| `TextView` | A read-only viewer for prose: word-wrapped, scrollable, appendable, and addressable in named `Region`s when you want to rewrite one part of the text in place. |
+| `ProgressBar` | A one-row bar — `█` over a `░` track — driven by `value` within a `Range`, or `indeterminate` for a bouncing sweep that owns its own ticker while on screen. |
+
+### Editing text — [book ch7](book/07-components.md#editing-text)
+
+| component | what it is |
+|---|---|
+| `TextField` | A single-line input with a real hardware caret, scrolling horizontally to keep the caret in view. |
+| `PasswordField` | A `TextField` that paints one mask glyph per character; editing, caret and clicks are unchanged. |
+| `TextArea` | A multi-line, word-wrapping input with a caret that moves by grapheme cluster, word-jumps, and a viewport that scrolls to follow it. |
+
+### Typed values — [book ch7](book/07-components.md#the-value-seam)
+
+| component | what it is |
+|---|---|
+| `IntegerField` | A one-row field whose `value` is an `Integer` or `nil`, filtering input to digits and one leading `-`. |
+| `FloatField` | The same, one Ruby type over: `value` is a `Float` or `nil`. |
+| `BigDecimalField` | The same for money, where a binary `Float` is the wrong answer. Tuile's one optional dependency — add `bigdecimal` yourself if you name this component. |
+
+### Choosing from a set — [book ch7](book/07-components.md#choosing-from-a-set)
+
+| component | what it is |
+|---|---|
+| `Checkbox` | A one-row boolean: `[x]` / `[ ]` plus a caption, toggled by Space, Enter or a click on the glyph or label. |
+| `List` | The workhorse: a scrollable column of *typed items*, one row each, rendered lazily by a `renderer` you supply and handing your callbacks the item itself. Add a `Cursor` (or `Cursor::Limited`) to make it navigable. |
+| `RadioGroup` | Single-select over a set of items, one row each, with the marker painted in front of the label. Its `value` is the selected item. |
+| `CheckboxGroup` | Multi-select over the same shape; its `value` is a frozen `Set` of the checked items. |
+| `Select` | The enum field: a one-row face plus a `▾`, dropping open a list of options. Claims no printable key but Space, so your app's own keys keep working while it has focus. |
+| `ComboBox` | A text field with a filtering dropdown — type to narrow, arrow to highlight, Enter to accept. Its `value` is the selected *item*, never the typed text. |
+| `ListDropdown` | The floating, non-focusable list that `Select` and `ComboBox` drop open, and the `Menu` variant an app can drive itself. You rarely instantiate it directly. |
+
+### Taking an action — [book ch7](book/07-components.md#taking-an-action)
+
+| component | what it is |
+|---|---|
+| `Button` | A one-row `[ caption ]` running a block on Enter, Space or a left click. Size it yourself: `caption.display_width + 4`. |
+
+### Overlays and windows — [book ch7](book/07-components.md#overlays)
+
+| component | what it is |
+|---|---|
+| `Popup` | The modal overlay host: it wraps any component, paints nothing itself, and is sized by `size=` (a `Size` or a `Fraction` of the screen) rather than by its content. ESC or `q` dismisses. |
+| `Notification` | A transient corner toast — `Notification.show("Saved")` — stacking messages in one box that a single ticker drains. Non-modal, and it never takes focus. |
+| `InfoWindow` | A `Window` of static lines, tiled or popped up. For read-only information you don't want to assemble by hand. |
+| `PickerWindow` | A `Window` of options identified by single keystrokes, firing a callback with the key that was pressed. |
+| `LogWindow` | A scrolling log view. Point your logger at a `LogWindow::IO` and lines land here from any thread, marshalled through the event queue. |
+
+The mixins those share — `HasValue` (the `value` / `empty?` / `clear` /
+`on_value_change` seam every input speaks), `HasContent` (one-child
+containers) and `HasCaption` (app-authored chrome text) — are the seams to
+include when you write your own; chapter 7's "value seam" section is the
+walkthrough.
 
 ## Geometry primitives