tuile 0.15.0 → 0.16.0

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,144 +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`; a `TabSheet` hides a pane by *detaching* it, deliberately — that is what fires the lifecycle hooks on every switch, and it stays the choice now that `Component#visible=` exists (`D_visibility`); 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 |
-| ~~DateField~~ | `AbstractWrappingField` + `HasBadInput` | **built** 2026-09-04 (`D_date_field`, book ch7), after re-tiering out of Tier 2 the same day: the v1 is manual entry only, so the calendar popup it was blocked on became a phase 2 (still Tier 2 below). Value is stdlib `Date`; a per-instance list of strftime `formats`, first whole match winning and `formats.first` written back on blur/ENTER. It filters *nothing* — a date's grammar is not prefix-closed, so the residue is reported through `HasBadInput` — and its empty well derives its own `HasPlaceholder` hint from the primary format. `%y` is rejected outright and the calendar is proleptic Gregorian, not Ruby's `Date::ITALY` |
-| 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 by decision (`D_caption_ownership`), so the seam is the layout's own cells: `ideas/form-layout.md` |
-| Email Field | nothing, per `D_bad_input` — its value *is* its input, so it has no bad-input state and contributes only a packaged regex; **re-tiered toward reject** |
-| Calendar grid for `DateField`, and the ~~Time~~ / DateTime twins | the grid needs the calendar popup over Popover (L). It is **phase 2** of a field that already ships (`D_date_field`, Tier 1 above), so nothing is blocked on it: a `DateField` is fully usable by typing, and the grid is additive — a second way to set the same `value`, placed with `ListDropdown#anchor_to`. Two things it inherits rather than re-decides: the month names it paints are the locale question of `ideas/locale.md`, and `PageUp`/`PageDown` stepping a month is deferred there too. The Time / DateTime twins no longer wait on that seam — it shipped (`D_locale`) — and `TimeField` shipped under `D_time_field` (2026-09-05) with **no** picker dropdown: a list of times carries no information a user lacks, so it fails the test the calendar grid passes (`D_mouse`). PageUp/PageDown step an hour instead, and its phase 2 is segment-aware Up/Down (the Qt / `dialog --timebox` model), shared with `DateField` |
-| 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. Designed
-   2026-09-03 and **half shipped the same day**: the caption goes to the layout
-   (fields do *not* include `HasCaption` — `D_caption_ownership`), and the error
-   *verdict* stays on the field as `Component::HasValidation` (one member,
-   `error_message`, `HasValue` includes it, painted as a red *well* —
-   `D_has_validation`). What is left is the container that reads the *message*
-   off the field and paints it inline-right, plus the required marker and helper
-   text: `ideas/form-layout.md`. Items 2 and 3 turn out to be the same seam cut
-   in two — this half is the *geometry*, item 3 is the *signals*.
-3. **Validation seam** → forms generally. Designed 2026-09-03 and split three
-   ways. The field-side channel **shipped the same day**: `HasBadInput`
-   (`D_bad_input`) holds the one fact only the field can know, because
-   `on_value_change` is a diff over values and every unrepresentable input
-   collapses onto the same one, and `on_blur` — the commit point it wanted —
-   shipped 2026-09-04 (`D_on_blur`); only the push notice is still deferred, for
-   want of a consumer. Still open: `ideas/binder.md`
-   (the consumer, and the four-layer model/transformations/value/input
-   vocabulary the whole cluster now uses). The `HasValidation` half **shipped
-   the same day** as well (`D_has_validation`), so what is left of item 2's note
-   is the container that paints the message. `Date Picker` is the component that
-   actually forces it; Email Field is re-tiered toward *reject*.
-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