tuile 0.14.0 → 0.16.0

data/book/08-testing.md

@@ -95,39 +95,119 @@ 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.walk_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
 is most of writing a good Tuile test.
 
-**Low: call the component directly.** {Tuile::Component#handle_key} and
-`handle_mouse` are public, and calling them straight tests a component's
-own logic in isolation — no focus, no dispatch, just "given this key, does
-the list move its cursor?" `handle_key` returns whether it consumed the
-key, so you assert on that too:
+**Low: call the component directly.** {Tuile::Component#handle_key?} and the
+`handle_mouse_*` handlers are public, and calling one straight tests a
+component's own logic in isolation — no focus, no dispatch, just "given this
+key, does the list move its cursor?" Both answer whether they consumed the
+event, so you assert on that too:
 
 ```ruby
-list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
+list.handle_key?(Keys::DOWN_ARROW)                            # exercises the cursor directly
+list.handle_mouse_scroll?(Mouse::ScrollEvent.new(:up, 5, 2))  # false at the top: an ancestor gets it
 ```
 
-**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:
+**A press, though, wants the high altitude.** It does not only *do* something:
+it focuses, it dismisses popups, and which component it even reaches is the
+router's answer rather than the component's — so calling `handle_mouse_down?`
+by hand tests a third of what a click is. Drive it through
+{Tuile::FakeScreen}, which posts the gesture the terminal would:
 
 ```ruby
-screen.content = list                      # a click focuses; focus needs a tree
+screen.content = list                      # a press focuses; focus needs a tree
 list.rect = Rect.new(0, 0, 10, 5)
-list.handle_mouse(MouseEvent.new(:left, 5, 2))
+screen.click(5, 2)                         # press then release, at that cell
 ```
 
-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.
+`click` is the whole gesture; `press` / `release` are its halves, for a test
+about what the grab does in between, and `scroll` / `move` post the other two
+events. They all take screen-absolute, 0-based coordinates, so a test asserts
+against the rect it assigned — and a press on a cell no component covers
+simply does nothing.
 
-**High: go through the pane.** {Tuile::ScreenPane#handle_key} runs the
+**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
 root. So when your test is about routing — that a layout's one-key pane jump
@@ -137,11 +217,11 @@ drive the pane and let the real machinery run:
 
 ```ruby
 screen.focused = list                # focus as production does — or list.focus
-assert screen.pane.handle_key("1")   # the layout's ancestor binding fires
+assert screen.pane.handle_key?("1")   # the layout's ancestor binding fires
 ```
 
 The two rungs *above* the pane have their own doors, because `Screen`'s own
-`handle_key` — the top of the ladder — is private: it belongs to the key
+`handle_key?` — the top of the ladder — is private: it belongs to the key
 thread, not to app code. Tab cycling is {Tuile::Screen#focus_next} /
 `focus_previous`, both already scoped to the topmost modal popup, which is
 what "a popup traps Tab" means. A global shortcut is a block you registered,

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#handle_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 `handle_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.
@@ -64,26 +65,35 @@ one, not to fill an outline.
    same queue rather than handled off the signal.
 5. **[Focus and the keyboard](05-focus.md).** The focus chain and
    `focusable?`, and the three-rung order in which a keystroke is offered
-   to the tree — Tab, global shortcuts, then `handle_key` delivered to
+   to the tree — Tab, global shortcuts, then `handle_key?` delivered to
    focus and bubbling up its ancestors. Why scope-wide keys (pane jumps, a
    form's default button) belong on an ancestor, why a paste rides its own
-   path rather than the ladder, and how to write a status line over
-   `on_focus_changed` — Tuile draws none for you.
+   path rather than the ladder, and how the mouse takes a road of its own —
+   a press bubbling to one claimant that is then grabbed. Ends on writing a
+   status line over `on_focus_changed` — Tuile draws none for you.
 6. **[Theming](06-theming.md).** Semantic color tokens read at paint
    time, opt-in component backgrounds that inherit down the tree
    (`bg_color`), light/dark auto-detection at startup and live OS
    appearance flips, pairing variants in a `ThemeDef`, app-specific custom
-   tokens, and rebuilding theme-derived content in `on_theme_changed`.
+   tokens, and rebuilding theme-derived content in `handle_theme_changed`.
 7. **[The component library](07-components.md).** A narrative tour of
    the shipped toolbox — the text inputs and views, the value fields, the
    selectors, Button, ProgressBar, Window, TabSheet, MenuBar, Popup and the
    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 `handle_locale_changed` is
+   for.

data/examples/file_commander.rb

@@ -20,6 +20,14 @@ require "rainbow"
 require "tuile"
 
 module FileCommanderExample
+  # `hint` is the app's token, not Tuile's — the framework carries accents only
+  # for the chrome it paints itself, and the status line below is ours. Paired
+  # in a ThemeDef so it survives an OS appearance flip.
+  APP_THEME = Tuile::ThemeDef.new(
+    dark: Tuile::Theme::DARK.with(custom: { hint: Tuile::Color::GREY54 }),
+    light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+  )
+
   # Pastel X11 colors chosen to read on a black background.
   TYPE_COLORS = {
     directory: :lightskyblue,
@@ -45,7 +53,7 @@ module FileCommanderExample
     attr_reader :cwd
     attr_accessor :on_cwd_changed
 
-    def handle_key(key)
+    def handle_key?(key)
       return false unless active?
 
       if Tuile::Keys::BACKSPACES.include?(key)
@@ -56,7 +64,7 @@ module FileCommanderExample
       end
     end
 
-    def on_focus
+    def handle_focus
       super
       @on_cwd_changed&.call
     end
@@ -135,13 +143,13 @@ module FileCommanderExample
       # The status line. Every key here works in both panes, so the row never
       # changes and nothing needs to watch focus — a status line is only worth
       # wiring to Tuile::Screen#on_focus_changed= when its text actually varies
-      # with the focused component. `theme.hint` bakes its colors in, so the
+      # with the focused component. `theme.fg` bakes its colors in, so the
       # one thing this label does watch is a light/dark flip.
       @status = Tuile::Component::Label.new
       render_status = lambda do
         t = screen.theme
-        @status.text = "q #{t.hint("quit")}  Tab #{t.hint("Switch")}  " \
-                       "Enter #{t.hint("Open")}  Bksp #{t.hint("Up")}"
+        @status.text = "q #{t.fg(:hint, "quit")}  Tab #{t.fg(:hint, "Switch")}  " \
+                       "Enter #{t.fg(:hint, "Open")}  Bksp #{t.fg(:hint, "Up")}"
       end
       render_status.call
       @status.on_theme_changed = render_status
@@ -180,6 +188,7 @@ unless File.directory?(start_dir)
 end
 
 screen = Tuile::Screen.new
+screen.theme_def = FileCommanderExample::APP_THEME
 commander = FileCommanderExample::FileCommander.new(start_dir, start_dir)
 screen.content = commander
 commander.left_window.focus

data/examples/hello_world.rb

@@ -11,18 +11,31 @@
 
 require "tuile"
 
+# `hint` is the app's token, not Tuile's: the framework carries accents for the
+# chrome *it* paints, and a status line is the app's own (Tuile draws none).
+# Pairing the two shades in a ThemeDef is what makes it survive the user
+# flipping OS appearance — a bare `theme=` would be replaced on the next flip.
+# Both greys quantize to :bright_black on a 16-color terminal, so the
+# description stays dimmer than the key beside it even there.
+APP_THEME = Tuile::ThemeDef.new(
+  dark: Tuile::Theme::DARK.with(custom: { hint: Tuile::Color::GREY54 }),
+  light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+)
+
 # Screen must exist before any Component is built: components reach for
 # Tuile::Screen.instance during invalidate/repaint hooks.
 screen = Tuile::Screen.new
+screen.theme_def = APP_THEME
 
 window = Tuile::Component::Window.new("Tuile")
 window.content = Tuile::Component::Label.new("Hello, world!")
 
-# The status line. `theme.hint` styles the *description* half of a "key what"
-# pair, and bakes the color in — so the label rebuilds itself from
-# `on_theme_changed` to follow a light/dark flip.
+# The status line. `theme.fg` styles the *description* half of a "key what"
+# pair — dimmed, so the key is the element that pulls the eye — and bakes the
+# color in, so the label rebuilds itself from its `on_theme_changed` slot to follow a
+# light/dark flip.
 status = Tuile::Component::Label.new
-render_status = -> { status.text = "q #{screen.theme.hint("quit")}" }
+render_status = -> { status.text = "q #{screen.theme.fg(:hint, "quit")}" }
 render_status.call
 status.on_theme_changed = render_status