tuile 0.13.0 → 0.15.0

data/book/08-testing.md

@@ -95,6 +95,84 @@ lives in the buffer; cursor behavior lives in `prints`. Keeping the two
 apart is deliberate, and mixing them up is the most common way a first
 Tuile test goes wrong.
 
+## Finding the component to drive
+
+Asserting on the buffer needs a `rect`; driving a component needs the
+component itself. For a two-line test you have it already — you just built
+it. The awkward case is the one that shows up as soon as an app grows: the
+widget you want to poke is four levels down inside something a *builder
+method* assembled, and the test never held a reference to it.
+
+{Tuile::Testing} is the answer. `Testing.get` walks the tree and returns the
+one component matching a spec:
+
+```ruby
+Testing.get(Component::Button, caption: "Save").handle_key(Keys::ENTER)
+Testing.get(id: :amount).value = 42
+```
+
+The spec is a class, an `id`, a caption, a block, or any combination of
+them — never a path through the hierarchy, which would break every time you
+nested one more layout. The class slot also takes a *mixin*, which is where
+the `Has*` family from chapter 7 pays off a second time:
+`Testing.find(Component::HasBadInput)` finds every field in the tree whose
+parse can fail, whatever their classes.
+
+The `id` in that second line is a plain `Symbol` tag you set on any
+component, purely so a test can ask for it back:
+
+```ruby
+amount = Component::IntegerField.new
+amount.id = :amount           # nothing paints this, and nothing reads it
+```
+
+`get` is strict on purpose: it raises unless *exactly one* component
+matches. That is the whole feature. The obvious thing to write by hand is a
+walk that takes the first match —
+
+```ruby
+combo = nil
+window.on_tree { |c| combo ||= c if c.is_a?(Component::ComboBox) }
+```
+
+— and the day the pane grows a second `ComboBox`, that silently re-points
+your test at a different widget. Nothing fails; the assertions just start
+describing something else. `get` calls that ambiguity what it is, and the
+failure comes with a dump of the tree it searched:
+
+```
+expected 1 Component::ComboBox, found 2
+searched:
+  #<ScreenPane rect=(0,0 160x50)>
+    #<Window rect=(0,0 40x10) caption="Settings">
+→     #<ComboBox rect=(1,1 38x1) value=nil>
+→     #<ComboBox rect=(1,2 38x1) value="dark">
+```
+
+Which usually tells you the fix immediately: narrow the search. Every
+lookup takes `in:` to scope it to a subtree, and by default searches the
+whole screen — popups included, since chapter 1's pane holds them under the
+same root as the content.
+
+```ruby
+Testing.get(Component::ComboBox, in: sampler.demo_window)
+```
+
+Its sibling `Testing.find` returns *all* matches as an array, and takes an
+optional `count:` — an Integer for exactly, a Range for a bound — so an
+assertion about how many of something exists is one call:
+
+```ruby
+Testing.find(Component::Checkbox, in: form, count: 3)   # raises unless 3
+```
+
+Two habits worth forming. Call these qualified, as `Testing.get(...)`:
+`find` and `get` are the most collision-prone names in a spec suite, so
+Tuile deliberately neither installs them on `Component` nor asks you to mix
+the module in. And remember this is *additive* — it makes driving a tree
+terser, and changes nothing about the assertion channel. What a component
+*shows* is still asserted on the buffer.
+
 ## Driving the system
 
 There are two altitudes at which you feed input, and picking the right one
@@ -108,9 +186,25 @@ key, so you assert on that too:
 
 ```ruby
 list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
+```
+
+**A mouse test needs the component mounted, where a key test doesn't.** A
+click doesn't only *do* something, it also *focuses* — and
+{Tuile::Screen#focused=} refuses a component that isn't on the pane, so
+`handle_mouse` on a component you never attached raises "is not attached to
+this screen". Give it a tree first:
+
+```ruby
+screen.content = list                      # a click focuses; focus needs a tree
+list.rect = Rect.new(0, 0, 10, 5)
 list.handle_mouse(MouseEvent.new(:left, 5, 2))
 ```
 
+That applies to containers too, and to more of them than you might expect:
+a click descends to every child whose rect contains the point, so testing a
+window's footer by clicking it exercises the window, the footer's slot and
+the footer, all of which want to be attached.
+
 **High: go through the pane.** {Tuile::ScreenPane#handle_key} runs the
 dispatch rung from chapter 5 that routing is actually about: delivery to
 {Tuile::Screen#focused}, then the bubble up its ancestor chain to the scope

data/book/09-styled-text.md

@@ -29,7 +29,7 @@ tangle has to be re-untangled on every edit.
 {Tuile::StyledString} untangles it once, structurally. A styled string is
 a sequence of **spans**, each a maximal run of characters that share one
 complete {Tuile::StyledString::Style} — foreground, background, bold,
-italic, underline, strikethrough. The spans are non-overlapping and tile
+italic, underline, strikethrough, inverse. The spans are non-overlapping and tile
 the whole string: every character belongs to exactly one span, and that
 span's `style` *is* the character's style. There are no overlay layers to
 merge, no running state to reconstruct. "What's the style at column 5?"
@@ -100,8 +100,8 @@ by default.**
 
 Strict means it recognizes exactly the SGR codes that map to a
 {Tuile::StyledString::Style}'s attributes — the foreground and background
-colors, bold, italic, underline, strikethrough — and *raises* on anything
-else. An unmodeled attribute like blink or reverse video, an unknown SGR
+colors, bold, italic, underline, strikethrough, inverse — and *raises* on
+anything else. An unmodeled attribute like blink or conceal, an unknown SGR
 code, a non-SGR escape like a cursor move or an OSC sequence: all of them
 are a {Tuile::StyledString::ParseError}, not a shrug. The reason is a
 contract worth protecting: `parse(to_ansi(x)) == x`. If parsing silently

data/book/10-locale.md

@@ -0,0 +1,216 @@
+# 10. Locale: the conventions, not the words
+
+Chapter 6 told one story about adapting to the user's environment: the
+terminal reports whether it is light or dark, Tuile picks a matching
+{Tuile::Theme}, and the whole UI restyles. This chapter tells the same
+story about a different fact — not what the terminal looks like, but how
+the *person* in front of it expects a date and a number to be spelled.
+
+The two are shaped alike on purpose. A frozen value type, detected once
+at startup, held on the screen, read at use time, replaceable at
+runtime, with a hook for anything that baked the old answer in. If you
+have read chapter 6, you already know the shape; what is worth your time
+here is the *boundary* — because this is the feature most likely to grow
+into something Tuile is not.
+
+## The one rule: conventions, never prose
+
+> A {Tuile::Locale} holds formatting conventions — how a value is
+> rendered and parsed. It never holds prose.
+
+That sentence is the whole design. It is what makes `Locale` a bag of
+about eight members rather than an internationalization subsystem, and
+it is the test a ninth member has to pass.
+
+The distinction is easy to feel once you see the two halves side by
+side. "Dates in this session are spelled `dd.mm.yyyy`" is a convention:
+it is a *rule* about rendering, it applies to every date the app will
+ever show, and Tuile can obey it without knowing anything about your
+app. "The date you typed is not valid" is prose: it is one sentence, in
+one language, that belongs to one widget, and translating it is a job
+with a catalogue, interpolation, and pluralization behind it. Tuile does
+the first and stays out of the second — a component's wording stays the
+component's own, settable where it matters.
+
+And the line is not Tuile's invention. POSIX drew it first: `LC_MESSAGES`
+carries the language your programs speak, `LC_TIME` and `LC_NUMERIC`
+carry the formatting conventions. Tuile reads the formatting categories
+and never the message one. That is why a session can coherently ask for
+an English UI *and* ISO dates *and* a decimal comma — three categories,
+three independent answers, which is exactly what one of your author's
+machines is configured to want.
+
+## What is in one
+
+```ruby
+locale = Tuile::Screen.instance.locale
+
+locale.date_formats        # => ["%Y-%m-%d"]   strftime patterns, primary first
+locale.time_formats        # => ["%H:%M:%S"]   ditto, at full precision
+locale.calendar_start      # => Date::GREGORIAN
+locale.first_weekday       # => 1              Monday, in Date#wday numbering
+locale.month_names[9]      # => "September"
+locale.abbr_day_names[1]   # => "Mon"
+locale.decimal_separator   # => "."
+```
+
+Two things about those last few are worth pausing on.
+
+**The name tables are keyed by the `Date` accessor that reads them.**
+`month_names[date.month]`, `day_names[date.wday]` — so you never do
+arithmetic to look a name up. That is why the two have different shapes:
+`Date#month` is 1-based, so the month tables are `Hash`es keyed `1..12`;
+`Date#wday` is 0-based, so the day tables are plain seven-element
+arrays. It looks like an inconsistency and is the opposite of one. A
+0-based month array would answer `month_names[9] # => "October"` — a
+*plausible wrong answer*, silently, in the calendar header of a
+month-view someone ships. The `Hash` makes that mistake impossible to
+express instead of merely documented against.
+
+**`date_formats` is a list, and the first entry is special.** Parsing
+tries them in order and the first whole match wins; the primary —
+`formats.first` — is also what gets *written* when a value is assigned or
+a loosely typed buffer is canonicalized. Lenient in, strict out. Which
+means only the primary has to survive a round-trip; a later entry only
+ever parses, so it is allowed to be lossy. Chapter 7 has the field-side
+story; {Tuile::Component::DateField} has the details.
+
+**`time_formats` keeps its seconds, and the field is what drops them.**
+This is the one member whose detected value is deliberately *more* than
+any field shows. glibc's `t_fmt` — where the conventions come from — is a
+**clock display** format, so it carries seconds nearly everywhere:
+`%H:%M:%S` under C, `%H.%M.%S` under Finnish. Honoring that in a form
+would put `:00` in front of every user who never asked for it, which is
+what WinForms and Ant Design both actually ship.
+
+So the seconds are dropped — but *in the field*, not here, and the
+distinction is the whole point. Dropping them is a **policy**, and a
+lossy one: a status-bar clock or a log timestamp legitimately wants
+`13:45:30`, and if the locale had already thrown the seconds away, it
+would have no way to ask for them back. A convention that carries less
+than the system said is not a convention any more. So the locale keeps
+the full spelling, {Tuile::Component::TimeField} reduces it to whatever
+its `step` calls for, and a consumer that wants the other answer still
+has one.
+
+What *does* happen at the boundary is expansion: libc's shorthands are
+rewritten into their parts (`%T` → `%H:%M:%S`, `%r` → `%I:%M:%S %p`) so
+no consumer has to know them. That is a representation change and
+nothing more, which is the line between what normalizes here and what
+does not.
+
+## Detection: ask the system, and only when it was asked
+
+Ruby exposes no locale data at all. There is no `nl_langinfo` binding,
+nothing on `Date`, nothing in `Etc`; `Date::MONTHNAMES` is frozen
+English under every `LC_ALL` you set, and `strftime("%x")` is a fixed
+American `%m/%d/%y` that merely *looks* like a locale channel. So
+{Tuile::Locale.system} shells out to `locale -k` — one subprocess of
+about a millisecond, whose answers are already strftime patterns, which
+is Tuile's own vocabulary rather than a second grammar to translate.
+
+The interesting part is not the subprocess. It is the gate in front of
+it.
+
+The C/POSIX default date format is American. That means "the user said
+nothing" and "the user wants `%m/%d/%y`" are *indistinguishable* from
+the answer — so a container with no `LANG` set would confidently show
+American dates to a Norwegian. Tuile therefore detects only when the
+environment actually said something: if the POSIX chain for a category
+is empty, or names `C` or `POSIX`, the probe's answer for that category
+is thrown away and {Tuile::Locale::ISO} stands.
+
+And the gate is *per category*, which is the part that surprises people.
+Gating once on "any locale variable is set" is wrong on a real machine:
+a session exporting only `LC_NUMERIC=de_DE.UTF-8` would open the gate,
+and then `d_fmt` — resolving through an unset `LC_TIME` and an unset
+`LANG` — comes back American. So the date conventions are kept only if
+`LC_ALL` / `LC_TIME` / `LANG` speaks, and the numeric one only if
+`LC_ALL` / `LC_NUMERIC` / `LANG` does. One subprocess, two gates.
+
+Everything else about detection is defensive, because none of it can be
+allowed to fail loudly at startup: `locale(1)`'s exit status is useless
+in both directions (a bad locale name exits 0 and quietly returns C; an
+unknown keyword exits 1 while printing every good key), so the status is
+ignored and each value is validated on its own. Anything that does not
+hold up falls back to its `ISO` member individually — not
+all-or-nothing. A missing binary, a Windows box, a musl container: `ISO`,
+no exception raised.
+
+## The floor is ISO 8601, and that is an argument
+
+{Tuile::Locale::ISO} is the only constant Tuile ships. There is no
+`EN_US`, no `DE`, and there will not be: two presets are a catalogue, a
+catalogue implies completeness, and completeness is a promise about the
+world's date conventions that a TUI toolkit has no business making. You
+build your own from `ISO`:
+
+```ruby
+screen.locale = Tuile::Locale::ISO.with(date_formats: ["%d.%m.%Y", "%Y-%m-%d"])
+```
+
+Every member is validated in the constructor, and `Data#with` re-runs the
+constructor — so an invalid `Locale` is unreachable by either route.
+
+`ISO` is a defensible floor rather than a default someone picked, because
+three of its members cite the same standard: ISO 8601 dates, an ISO 8601
+week starting Monday, and the proleptic Gregorian calendar ISO 8601
+mandates. The names are Ruby's own frozen English tables, re-keyed but
+not authored — so Tuile ships zero locale data of its own, even in the
+fallback. And the decimal separator is `"."` not because ISO says so (ISO
+31-0 rather prefers the comma) but because `Float#to_s` writes a dot and
+a field's `value=` goes through it: any other floor would make a numeric
+field disagree with itself before you configured anything.
+
+## Fields follow the session unless you say otherwise
+
+A {Tuile::Component::DateField} takes both of its conventions from
+`Screen#locale` until you assign them. So the common cases are one line
+each, and they compose:
+
+```ruby
+screen.locale = Locale::ISO.with(date_formats: ["%d.%m.%Y"])  # every field
+field.formats = "%Y-%m-%d"                                    # this one only
+field.formats = nil                                           # follow again
+```
+
+`nil` restoring inheritance is the same shape `placeholder=` and
+`bg_color=` already use, and it is what keeps the two decisions
+independent: overriding one field is not opting it out of the session
+forever.
+
+## When the locale changes under you
+
+{Tuile::Screen#locale=} fires {Tuile::Component#on_locale_changed}
+across the attached tree and then invalidates all of it — the same
+machinery {Tuile::Screen#theme=} uses, for the same reason.
+
+Because everything repaints, anything your code *pulls* at paint or parse
+time needs no hook at all. A date field parses its buffer on read; a
+calendar grid would look month names up while painting. Both simply come
+out right on the next frame.
+
+The hook is for state you *pushed* somewhere when you last read the
+conventions. A date field's typing hint is the worked example: it lives
+in its editor's `placeholder`, written when the formats were last set, so
+a repaint alone would faithfully repaint the stale `dd.mm.yyyy`. The
+field overrides `on_locale_changed` to re-derive it — and, while it is
+there, to rewrite a buffer that still parses into the new primary format.
+Your own code does the same for a date you rendered into a
+{Tuile::Component::Label}, either by overriding the hook or by assigning
+the listener:
+
+```ruby
+label.on_locale_changed = -> { label.text = due.strftime(screen.locale.date_formats.first) }
+```
+
+One consequence to accept rather than defend against: a field holding a
+half-typed buffer when the grammar changes under it may stop parsing, and
+will then read as bad input. That is correct — the text is still there,
+the user can see it, and they can fix it. A locale change is a
+once-a-session event, not something worth contorting a field to survive.
+
+The other rule inherited from chapter 6 applies unchanged: **read the
+locale at use time; never cache it in an ivar.** A cached one strands on
+the old conventions the moment someone assigns a new locale, and nothing
+raises to tell you.

data/book/README.md

@@ -29,9 +29,10 @@ theming (including live OS light/dark flips). Chapters 7–8 close out
 **narratively** — a tour of the shipped component toolbox framed around
 when and why to reach for each, and how to test a Tuile app end to end.
 Those two lean on the rdoc for the exact APIs; the guide keeps to the
-walkthroughs and use-cases. Chapter 9 is a **deep dive** on
-`Tuile::StyledString`, the text primitive under everything the framework
-draws — read it when you start rendering your own styled content.
+walkthroughs and use-cases. Chapters 9–10 are **deep dives** on one
+piece each, to read when you need them: `Tuile::StyledString`, the text
+primitive under everything the framework draws, and `Tuile::Locale`, the
+formatting conventions a date or a number is spelled by.
 
 The book grows organically — a chapter exists when a concept has earned
 one, not to fill an outline.
@@ -80,10 +81,18 @@ one, not to fill an outline.
    window conveniences — framed around *when and why* you reach for each.
    Signatures stay in the rdoc.
 8. **[Testing a Tuile app](08-testing.md).** The testing approach:
-   `FakeScreen`, asserting against the painted buffer, driving
-   invalidation, and PTY-based end-to-end tests of runnable scripts.
+   `FakeScreen`, asserting against the painted buffer, locating the
+   component to drive with `Tuile::Testing`, driving invalidation, and
+   PTY-based end-to-end tests of runnable scripts.
 9. **[Styled text](09-styled-text.md).** A deep dive on
    `Tuile::StyledString`, the span-based "text plus styling" value type
    under everything Tuile draws: why spans instead of a `String` full of
    escape codes, the style-aware algebra (slice/wrap/concat by display
    column), minimal-diff rendering, and the strict-vs-lenient parser.
+10. **[Locale](10-locale.md).** The other environment fact, shaped like
+   chapter 6's theme: `Tuile::Locale` holds *formatting conventions and
+   never prose*, detected from `locale(1)` only when the environment
+   actually asked, with `Locale::ISO` as the floor. Why the name tables
+   are keyed by the `Date` accessor that reads them, how a field follows
+   the session until you override it, and what `on_locale_changed` is
+   for.

data/examples/file_commander.rb

@@ -82,7 +82,7 @@ module FileCommanderExample
       @on_cwd_changed&.call
     rescue SystemCallError => e
       @cwd = previous
-      Tuile::Component::InfoWindow.open("Cannot open", [path, e.message])
+      Tuile::Component::InfoWindow.open("Cannot open", "#{path}\n#{e.message}")
     end
 
     def load_entries