tuile 0.14.0 → 0.15.0

data/README.md

@@ -148,6 +148,15 @@ read — `Screen#background_color` — for panes tinted a few percent off the
 terminal's own, LazyVim-style.
 → [chapter 6](book/06-theming.md)
 
+**A `Locale` holds conventions, never prose.** Date formats, the calendar,
+month and weekday names, the decimal separator — detected from `locale(1)` at
+startup, but only when the environment actually asked for something, since the
+POSIX default is American and "said nothing" is indistinguishable from "wants
+American". Everything else falls back to `Locale::ISO`. Tuile ships no message
+catalogue and no per-country presets: this is the formatting half of what POSIX
+splits, and the wording half stays your app's.
+→ [chapter 10](book/10-locale.md)
+
 ## Components
 
 Every component lives under `Tuile::Component::*`, and every one of them is a
@@ -198,6 +207,8 @@ carries the per-method reference: `bundle exec rake yard`, or
 | `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. |
+| `DateField` | A one-row field whose `value` is a `Date` or `nil`, over a list of strftime formats taken from `Screen#locale`: it accepts any of them and writes the first one back when you leave the field. Manual entry — there is no calendar popup yet. |
+| `TimeField` | A one-row field whose `value` is a time of day — a `Time` on a fixed epoch date, or `nil` — spelled the way `Screen#locale` says. `step` is both the Up/Down stride and the precision: it shows seconds only when set below a minute. |
 
 ### Choosing from a set — [book ch7](book/07-components.md#choosing-from-a-set)
 
@@ -231,10 +242,13 @@ carries the per-method reference: `bundle exec rake yard`, or
 | `LogWindow` | A `Window` framing a `LogTextView` — the framed log pane. |
 
 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.
+`on_value_change` seam every input speaks), `HasValidation` (`error_message`,
+the verdict a validator writes and the field shows as a red well), `HasBadInput`
+(`bad_input?`, for a field whose input can be something its value cannot
+represent — a lone `-` in a number), `HasContent` (a primary child the caller
+populates, named `content`) 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
 
@@ -258,7 +272,7 @@ Tuile.logger = Logger.new(Tuile::Component::LogTextView::IO.new(view))
 ## Testing
 
 Tuile ships with a `Tuile::FakeScreen` that you install in place of the real
-screen for unit tests. It fixes the viewport at 160×50, disables the UI lock,
+screen for unit tests. It fixes the viewport at 160×50,
 paints into an in-memory back buffer (assert on it for painted content) while
 capturing cursor/housekeeping escapes into an array, and uses a synchronous
 `FakeEventQueue` (submitted blocks run inline; posted events are discarded).
@@ -303,6 +317,12 @@ Key hooks:
   to its current value should typically *not* invalidate.
 - `Screen.instance.clear` — drops accumulated `prints` without resetting
   invalidation.
+- `Tuile::Testing.get` / `.find` — locate a component to drive, by class,
+  mixin, `Component#id`, caption or a block:
+  `Testing.get(Component::Button, caption: "Save")`. `get` demands exactly
+  one match and prints the tree it searched when it doesn't get one; `find`
+  returns all matches and takes `count:`. Both take `in:` to scope the
+  search, and default to the whole screen. Call them qualified.
 
 Because `FakeEventQueue#submit` runs the block immediately on the calling
 thread, code paths that marshal work back via `screen.event_queue.submit { … }`

data/TERMINOLOGY.md

@@ -24,6 +24,8 @@ needs a paragraph of justification, that paragraph belongs in one of those three
 | **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:
@@ -57,15 +59,27 @@ content-space.
 | **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. |
+| **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*, which is how Tuile hides a component. |
+| **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 explicit background an input paints over its whole rect (`Theme#input_bg_color` / `#active_bg_color`), which opts it out of `bg_color` inheritance. |
+| **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/book/05-focus.md

@@ -73,6 +73,24 @@ that scope in tree order and advances by one, wrapping around; Shift+Tab
 walks backward. This is what keeps Tab from escaping an open dialog — the
 scope is the dialog, so cycling stays inside it.
 
+There is a third gate, and it isn't a predicate you override:
+{Tuile::Component#visible?}. A hidden component — or any component under a
+hidden one — is skipped by Tab, by click-to-focus, and by the forwarding a
+container does, because it is skipped by the walk that collects candidates
+at all. You never write a `visible?` check yourself; chapter 7 covers what
+the flag is for.
+
+The rule to know here is what happens when you hide the thing that
+currently *has* focus. Focus does not stay there, and it does not become
+nothing either: it moves to the hidden component's parent, which forwards
+it on to the first field it can reach — exactly what happens when a
+component is removed from the tree. Nothing is stashed, so bringing the
+component back does not bring focus back with it. That is the same
+behaviour a browser and every desktop toolkit settle on, and the reason
+Tuile can't simply drop focus is worth knowing: with focus at nothing, keys
+reach nobody at all, so an unhandled `q` would fall through to the event
+loop and quit your app.
+
 ## The dispatch order
 
 When a key arrives, it's offered to the tree in a fixed order, and the
@@ -207,8 +225,10 @@ marker, reads the payload raw up to the terminator, and posts it as a
 single `PasteEvent` — which never enters the ladder at all:
 
 - no Tab traversal, no global shortcuts, no `handle_key`;
-- straight to {Tuile::Component#handle_paste}, delivered down the focus
-  chain and bubbling exactly like a key;
+- straight to {Tuile::Component#handle_paste} on the focused component —
+  and *only* it: unlike a key, a paste does not bubble to ancestors, because
+  the reasons a key does are all about scope-wide bindings and none of them
+  wants a clipboard;
 - the whole clipboard as one `String`, `\n`-normalized.
 
 The default `handle_paste` returns `false` and the text is dropped.
@@ -273,6 +293,47 @@ needed. With dispatch resting on nothing but "did you return `true`," the
 proxy is gone, and a component's decision to consume a key is the only
 declaration in the system.
 
+## A component that reacts to its own focus
+
+Two hooks tell a component about itself, and a component overrides them —
+nothing else calls them. {Tuile::Component#on_focus} fires when it gains
+focus; {Tuile::Component#on_blur} fires when it loses it. Both fire on that
+one component, never on the ancestors that light up and go dark with it.
+
+`on_focus` is the forwarding hook. It's how a {Tuile::Component::Window}
+handed focus passes it to its content, and how a {Tuile::Component::Layout}
+skips ahead to the first tab stop underneath it — which is also why it fires
+on *every* assignment, even one that re-focuses what's already focused.
+
+`on_blur` is the commit point. Nothing else in Tuile is one: Tab is
+unconditional, so a user leaving a half-finished field usually leaves by a
+key no component ever sees, and `on_enter` never fires. If your field wants
+to tidy up what was typed, this is where:
+
+```ruby
+class TrimmedField < Tuile::Component::TextField
+  protected def on_blur = (self.text = text.strip)
+end
+```
+
+Both hooks fire on one component, so a *composed* widget — a
+{Tuile::Component::ComboBox}, whose inner field is what actually holds focus —
+gets the blur on the child, not on itself. When the question is "has focus left
+this whole widget", override `active=` instead and compare before and after;
+that's exactly what the combo box does to close its dropdown when you tab away.
+
+It is a notification, not a veto — focus has already moved by the time you
+hear about it, and a handler that tries to hold focus is picking a fight with
+the one key nothing can suppress. It also fires wherever focus is *dropped*,
+not only where a user moved it: when a popup closes, the component being
+blurred has usually been detached already, so an `invalidate` there does
+nothing; and `screen.close` blurs the focused component on its way out. Keep
+the handler cheap and it won't matter.
+
+The framework sends both hooks with `__send__`, so declare them public,
+protected or private as you like — the example above groups `on_blur` under
+`protected`, which is where framework-invoked plumbing belongs.
+
 ## Writing a status line
 
 Chapter 1 pointed out that Tuile draws no status bar. This is the chapter

data/book/06-theming.md

@@ -23,18 +23,28 @@ defaults for free.
 
 What Tuile *does* color is the small set of cues that signal
 interaction: the highlight behind the focused list row, the border of the
-active window, the resting "well" of a text field, the shortcut captions
+active window, the resting "well" of a text field, the scrollbar down a
+scrollable pane's edge, the shortcut captions
 in a status line you write. Those are the accents, and they are exactly the tokens
 a {Tuile::Theme} carries — `active_bg_color`, `active_border_color`,
-`input_bg_color`, `hint_color`. There is no global `bg` or `fg` token,
+`input_bg_color`, `scrollbar_color`, `hint_color`, the three that mark a field
+invalid (`error_color` and the two error wells), and `placeholder_color` for
+the hint an empty field paints into itself. There is no global `bg` or `fg` token,
 and that absence is intentional: adding one would mean painting over the
 terminal's defaults everywhere, which is precisely the thing that makes a
 TUI look wrong on someone else's color scheme. The theme touches only
 what the framework must color to be legible, and leaves the rest to the
 terminal.
 
-So a {Tuile::Theme} is a frozen value type — a `Data.define` of four
-colors plus an app-extensible `custom` hash — and that's all. Two are
+Two of them are worth a second look, because they pull in opposite
+directions. `hint_color` is an *accent* — a blue that draws the eye to a
+shortcut caption you want noticed. `placeholder_color` is its temperamental
+opposite: a grey tuned to sit just above invisible, because a placeholder is
+a hint the reader is welcome to miss. Reaching for the wrong one of the two
+makes an empty field louder than a filled one.
+
+So a {Tuile::Theme} is a frozen value type — a `Data.define` of colors
+plus an app-extensible `custom` hash — and that's all. Two are
 built in: {Tuile::Theme::DARK}, the colors Tuile has always used, and
 {Tuile::Theme::LIGHT}, counterparts legible on a pale background.
 
@@ -66,9 +76,47 @@ terminal default is just the root of that chain, which is why an unset
 
 A widget with a background of its *own* keeps it. A text field paints its
 well across its whole rect, so dropping one into a tinted panel shows the
-field in its own well, not the panel tint — the explicit background wins
-over the inherited one, the terminal equivalent of a CSS element that sets
-its own `background`.
+field in its own well, not the panel tint — the terminal equivalent of a CSS
+element that sets its own `background`. That is a *default*, though, not a
+refusal: set `bg_color` on the field itself and it wins, because the chain
+asks three questions in order — what did the app set on this component, what
+background does this widget claim of its own, and what surrounds it.
+
+Which is also how you get a field that reads as plain text inside a tinted
+prompt. You *can* name the panel's colour again on the field — but there is a
+shorter way to say "I have no background of my own, use whatever is behind me":
+
+```ruby
+field.bg_color = Component::BG_INHERIT
+```
+
+That is CSS's `background: inherit`, and it is different from leaving
+`bg_color` unset: unset means "ask *my* default first", which for a field is
+its well. `BG_INHERIT` skips the well and goes straight to what surrounds it.
+
+It is the same mechanism Tuile uses internally. A
+{Tuile::Component::ComboBox} is one widget with one surface, built out of a
+{Tuile::Component::TextField} plus a `▾` — so the ComboBox paints the well and
+marks its inner field `BG_INHERIT`. Exactly one well per widget, which is what
+lets you tint the ComboBox and have the tint reach the cells the field draws.
+
+Backgrounds can differ by state. An input is brighter while it holds focus,
+and a flat `bg_color` replaces *both* shades — fine for a field, which shows a
+caret when focused, and a deliberate choice for something like a
+{Tuile::Component::Select}, which has no caret and nothing else to indicate
+focus with. Name the states when you want to keep the distinction:
+
+```ruby
+field.bg_color = grey                            # flat: focused or not
+field.bg_color = { normal: grey, active: blue }  # your own pair
+field.bg_color = { active: blue }                # keep the widget's own well,
+                                                 # override only the focus shade
+```
+
+The keys are a small closed set (`:normal`, `:active`) that Tuile defines —
+a state with no key simply isn't answered there, and the question falls
+through to the next level of the chain, which is what makes the third line
+above mean what it reads as.
 
 `bg_color` takes either a concrete {Tuile::Color} or a *live theme
 reference* — `Theme.ref(:panel_bg)` — that names one of your app's custom