tuile 0.14.0 → 0.15.0

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/sampler.rb

@@ -109,6 +109,37 @@ module SamplerExample
     end
   end
 
+  # A {Tuile::Component::TextArea} that steers a {Tuile::Component::ListDropdown}
+  # while it is open: movement keys move the highlight, ENTER accepts and ESC
+  # dismisses, and everything else — printables, editing, the ENTER that inserts
+  # a newline with no menu up — stays the TextArea's own.
+  #
+  # Subclassing *is* the seam for this. A component receives keys through
+  # `handle_key`, so one that wants different keys overrides it (here its
+  # `handle_text_input_key` hook) and calls `super` for the rest, which composes
+  # and stacks. None of this is baked into TextArea.
+  class SlashCommandTextArea < Tuile::Component::TextArea
+    # @param overlay [Tuile::Component::ListDropdown] the menu to steer.
+    def initialize(overlay)
+      super()
+      @overlay = overlay
+    end
+
+    protected
+
+    def handle_text_input_key(key)
+      return super unless @overlay.open?
+      return true if @overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
+
+      case key
+      when Tuile::Keys::ENTER then @overlay.choose
+      when Tuile::Keys::ESC then @overlay.close
+      else return super
+      end
+      true
+    end
+  end
+
   # Top-level sampler component: a shell row across the top — a
   # {Tuile::Component::MenuBar} of the demos, grouped, and a
   # {Tuile::Component::ComboBox} jump box at its right end — over one demo
@@ -199,7 +230,11 @@ module SamplerExample
                  Menu.new("Typed", "y", [
                             Entry.new("IntegerField", :build_integer_field, "i"),
                             Entry.new("FloatField", :build_float_field, "f"),
-                            Entry.new("BigDecimalField", :build_big_decimal_field, "b")
+                            Entry.new("BigDecimalField", :build_big_decimal_field, "b"),
+                            Entry.new("DateField", :build_date_field, "d"),
+                            Entry.new("TimeField", :build_time_field, "t"),
+                            Entry.new("Bad input", :build_bad_input, "a"),
+                            Entry.new("Validation", :build_validation, "v")
                           ]),
                  Menu.new("Choose", "c", [
                             Entry.new("Checkbox", :build_checkboxes, "c"),
@@ -227,6 +262,7 @@ module SamplerExample
                  Entry.new("Narrow strips", :build_narrow_strips, "n"),
                  Entry.new("Layout", :build_layout, "l"),
                  Entry.new("Background", :build_background, "b"),
+                 Entry.new("Visibility", :build_visibility, "v"),
                  Entry.new("Focus & Tab", :build_focus_demo, "f")
                ])
     ].freeze
@@ -309,10 +345,13 @@ module SamplerExample
 
     def build_text_field
       prompt = Tuile::Component::Label.new
-      prompt.text = "Tab here, then type. Arrows, Home/End, Backspace, Delete all work."
+      prompt.text = "Tab here, then type. Arrows, Home/End, Backspace, Delete all work.\n" \
+                    "While it is empty it shows a placeholder — a hint in ink faint " \
+                    "enough to miss, which is the point."
       field = Tuile::Component::TextField.new
+      field.placeholder = "dd.mm.yyyy"
       form do |f|
-        f.add(prompt, Fixed[1])
+        f.add(prompt, Fixed[2])
         f.add(field, Fixed[1])
       end
     end
@@ -408,6 +447,8 @@ module SamplerExample
       prompt.text = "Tab here, then type digits (and a leading -). Non-digits are ignored.\n" \
                     "Up/Down step the value by one; an empty field counts as 0."
       field = Tuile::Component::IntegerField.new
+      # Set on the composed field, not on the TextField inside it.
+      field.placeholder = "1-65535"
       status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
       field.on_value_change = ->(value) { status.text = "value: #{value.inspect}" }
       form do |f|
@@ -454,6 +495,185 @@ module SamplerExample
       end
     end
 
+    # DateField: several formats in, one format out. Type a date in any of the
+    # three spellings this pane accepts and Tab away — the field rewrites it in
+    # the *first* one, which is how the user sees that it understood them. Both
+    # halves of the settling rule are visible here too: nothing reddens while a
+    # date is being typed, and a buffer that never parsed reddens on the way
+    # out. The echo row is deliberately driven by `on_value_change` alone, so
+    # garbage leaves it stale: bad_input? is a *pull*, and the button is the "a
+    # form asks once, at the click" gesture that consults it (it also gives Tab
+    # somewhere to go, which is what makes both behaviours visible at all).
+    def build_date_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then type 4.9.2026 — or 09/04/2026, or 2026-09-04.\n" \
+                    "Tab away or press Enter and a buffer that parses is rewritten as yyyy-mm-dd;\n" \
+                    "one that doesn't is left as you typed it, and *then* the well goes red.\n" \
+                    "Up/Down step a day, and an empty field steps to today."
+      field = Tuile::Component::DateField.new
+      field.formats = ["%Y-%m-%d", "%d.%m.%Y", "%m/%d/%Y"]
+      status = Tuile::Component::Label.new
+      # to_s, not inspect: Date#inspect spells out the Julian day and the
+      # calendar reform, which is noise next to the one fact this row is for.
+      report = -> { status.text = "value: #{field.value&.to_s || "nil"}    bad_input?: #{field.bad_input?}" }
+      report.call
+      field.on_value_change = ->(_value) { report.call }
+      ask = Tuile::Component::Button.new("Ask again") { report.call }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(field, Fixed[1], cross: Fixed[20])
+        f.add(status, Fixed[1])
+        f.add(ask, Fixed[1], cross: Fixed[button_width(ask)])
+      end
+    end
+
+    # TimeField: one knob for two things, and the reason it is one. Both fields
+    # below sit under a *Finnish* spelling that this pane installs on the
+    # screen, because the whole point is invisible under ISO: switching
+    # precision must not cost you the locale's separator. So the left field
+    # shows 13.45 and the right 13.45.00 — a dot either way, which a per-field
+    # format override could not have managed.
+    def build_time_field
+      # Assigned here rather than detected, so the pane demonstrates the same
+      # thing on an American box as on a Finnish one.
+      Tuile::Screen.instance.locale = Tuile::Locale::ISO.with(time_formats: ["%H.%M.%S", "%H:%M:%S"])
+      prompt = Tuile::Component::Label.new
+      prompt.text = "The session spells times the Finnish way (13.45). Tab into either field.\n" \
+                    "Up/Down step a minute on the left, a second on the right (PageUp/PageDown an hour in both) —\n" \
+                    "one knob, because precision is a property of the format the buffer holds.\n" \
+                    "Note the dot survives the switch: that is what a per-field format would cost."
+      minutes = time_field_with(step: 60)
+      seconds = time_field_with(step: 1)
+      status = Tuile::Component::Label.new
+      report = lambda do
+        status.text = "minutes: #{minutes.value&.strftime("%H:%M:%S") || "nil"} (#{minutes.formats.first})    " \
+                      "seconds: #{seconds.value&.strftime("%H:%M:%S") || "nil"} (#{seconds.formats.first})"
+      end
+      report.call
+      [minutes, seconds].each { _1.on_value_change = ->(_value) { report.call } }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(labelled("Minute stride", minutes, field_width: 12), Fixed[1], cross: Fixed[30])
+        f.add(labelled("Second stride", seconds, field_width: 12), Fixed[1], cross: Fixed[30])
+        f.add(status, Fixed[1])
+      end
+    end
+
+    # @param step [Integer]
+    # @return [Tuile::Component::TimeField]
+    def time_field_with(step:)
+      Tuile::Component::TimeField.new.tap do |field|
+        field.step = step
+        field.set_to(13, 45)
+      end
+    end
+
+    # HasBadInput: the one fact on_value_change cannot carry. Type a lone "-"
+    # and watch the echo row stay silent — the value was nil before and is nil
+    # after, so there is no diff to report — while Save, which asks bad_input?
+    # instead of empty?, refuses and names the field.
+    def build_bad_input
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Type a lone '-' into Amount (or '1e' into Rate), then press Save.\n" \
+                    "Both read value: nil and empty?: true, exactly like an untouched field —\n" \
+                    "which is why a form must ask bad_input? before it saves a nil over your work."
+      # The one pane that tags its widgets with `id`, so the sampler's own spec
+      # can drive them through Tuile::Testing.get by name.
+      amount = Tuile::Component::IntegerField.new.tap { _1.id = :amount }
+      rate = Tuile::Component::FloatField.new.tap { _1.id = :rate }
+      echo = Tuile::Component::Label.new.tap { _1.text = "on_value_change: (nothing yet)" }
+      amount.on_value_change = ->(v) { echo.text = "on_value_change: amount = #{v.inspect}" }
+      rate.on_value_change = ->(v) { echo.text = "on_value_change: rate = #{v.inspect}" }
+      save = Tuile::Component::Button.new("Save") { save_form("Amount" => amount, "Rate" => rate) }
+      save.id = :save
+      rows = group do |g|
+        g.add(labelled("Amount", amount), Fixed[1])
+        g.add(labelled("Rate", rate), Fixed[1])
+      end
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(rows, Fixed[2])
+        f.add(echo, Fixed[1])
+        f.add(save, Fixed[1], cross: Fixed[button_width(save)])
+      end
+    end
+
+    # The login form of `D_has_validation`: the click writes a verdict onto
+    # each field and the field paints itself red, while *this* pane owns the
+    # cells the messages go in — one Label per field, refilled from
+    # `on_error_message_change`. Note the handler sets *or clears* on every
+    # pass, which is the whole writer discipline; and that no field computes
+    # anything, so nothing here fights the fields' own `bad_input?`.
+    def build_validation
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Press Log in empty, then with a 2-letter username: the message lands in\n" \
+                    "this pane's cells (via a listener) and the field's well turns red.\n" \
+                    "Tab between them — an invalid field still shows which one has focus."
+      username = Tuile::Component::TextField.new
+      password = Tuile::Component::PasswordField.new
+      fields = { "Username" => username, "Password" => password }
+      rows = group do |g|
+        fields.each { |caption, field| g.add(validated_row(caption, field), Fixed[1]) }
+      end
+      login = Tuile::Component::Button.new("Log in") { validate_login(fields) }
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(rows, Fixed[2])
+        f.add(login, Fixed[1], cross: Fixed[button_width(login)])
+      end
+    end
+
+    # @param caption [String]
+    # @param field [Tuile::Component] a field carrying {Tuile::Component::HasValidation}.
+    # @return [Tuile::Component] a row of caption, field, and the error Label
+    #   the field's listener keeps current.
+    def validated_row(caption, field)
+      error = Tuile::Component::Label.new
+      field.on_error_message_change = ->(msg) { error.text = msg || Tuile::StyledString::EMPTY }
+      row do |r|
+        r.add(Tuile::Component::Label.new(caption), Fixed[14])
+        r.add(field, Fixed[22])
+        r.add(error, Expand[1])
+      end
+    end
+
+    # Two rules, so the pane shows both halves: "required" has nothing to tint,
+    # "too short" does.
+    # @param fields [Hash{String => Tuile::Component}] caption => field.
+    def validate_login(fields)
+      fields.each { |caption, field| field.error_message = login_problem(caption, field) }
+      return if fields.each_value.any?(&:error_message)
+
+      Tuile::Component::ConfirmWindow.alert("Logged in", "Welcome, #{fields["Username"].value}.")
+    end
+
+    # @param caption [String]
+    # @param field [Tuile::Component]
+    # @return [String, nil] the verdict, or `nil` — the *clear* half of
+    #   set-or-clear-on-every-pass, without which a fixed field stays red.
+    def login_problem(caption, field)
+      return "#{caption} is required" if field.empty?
+      return "at least 3 characters" if field.value.length < 3
+
+      nil
+    end
+
+    # The Save gate of `D_bad_input`: asked once, at the click, so the
+    # continuously-true fact ("2" is a bad date on the way to "2026") is only
+    # ever read in a settled state.
+    # @param fields [Hash{String => Tuile::Component}] caption => field.
+    def save_form(fields)
+      bad = fields.filter_map do |caption, field|
+        "#{caption}: #{field.bad_input_message}" if field.respond_to?(:bad_input?) && field.bad_input?
+      end
+      if bad.empty?
+        values = fields.map { |caption, field| "#{caption}: #{field.value.inspect}" }
+        Tuile::Component::ConfirmWindow.alert("Saved", values.join("\n"))
+      else
+        Tuile::Component::ConfirmWindow.alert("Cannot save", "#{bad.size} problem(s):\n#{bad.join("\n")}")
+      end
+    end
+
     # @param value [BigDecimal, nil]
     # @return [String] the value tripled exactly, next to the same sum in Float.
     def triple_report(value)
@@ -495,19 +715,17 @@ module SamplerExample
     # A ListDropdown driven from a TextArea — the same shape {ComboBox} and
     # {Select} use, but wired by app code onto a field that knows nothing about
     # it. Focus (and the caret) stays in the TextArea the whole time: an
-    # `on_change` listener refills the menu, and an `on_key` interceptor hands
-    # movement keys to `#move` and Enter to `#choose` while it is open. None of
-    # this is baked into TextArea.
+    # `on_change` listener refills the menu, and {SlashCommandTextArea} hands
+    # movement keys to `#move` and Enter to `#choose` while it is open.
     def build_slash_demo
       prompt = Tuile::Component::Label.new
       prompt.text = "A ListDropdown driven from a TextArea. Type a slash command\n" \
                     "(try \"/\" or \"/s\"). The menu floats over the field without taking\n" \
                     "focus: Down/Up move the selection, Enter accepts, ESC dismisses, and\n" \
                     "ordinary typing keeps editing the field and refilters the menu."
-      area = Tuile::Component::TextArea.new
-
       overlay = Tuile::Component::ListDropdown.new
       @slash_overlay = overlay
+      area = SlashCommandTextArea.new(overlay)
 
       refill = lambda do
         matches = slash_matches(area)
@@ -524,20 +742,6 @@ module SamplerExample
 
       area.on_change = ->(_text) { refill.call }
       overlay.on_item_chosen = ->(_idx, item) { accept_slash_command(area, item.to_s) }
-      area.on_key = lambda do |key|
-        next false unless overlay.open?
-        next true if overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
-
-        case key
-        when Tuile::Keys::ENTER
-          overlay.choose
-        when Tuile::Keys::ESC
-          overlay.close
-          true
-        else
-          false
-        end
-      end
 
       form do |f|
         f.add(prompt, Fixed[4])
@@ -668,6 +872,42 @@ module SamplerExample
       end
     end
 
+    # `visible=` on a conditional form: the fields a checkbox above them
+    # governs. The rows close up completely when they go — a hidden child costs
+    # neither its slot nor the box's `spacing` gap, which is what separates it
+    # from a `Fixed[0]` collapse — and come back with their constraints and
+    # their typed text intact, since nothing was ever detached.
+    def build_visibility
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tick 'Business customer' to reveal two more fields.\n" \
+                    "The rows close up with no double gap, Tab skips what is hidden,\n" \
+                    "and text typed into a field survives being hidden and shown."
+      status = Tuile::Component::Label.new
+      company = labelled("Company", Tuile::Component::TextField.new)
+      vat = labelled("VAT id", Tuile::Component::TextField.new)
+      conditional = [company, vat]
+      business = Tuile::Component::Checkbox.new("Business customer")
+      apply = lambda do
+        conditional.each { _1.visible = business.checked? }
+        status.text = "visible fields: #{business.checked? ? 4 : 2}"
+      end
+      business.on_value_change = ->(_) { apply.call }
+      # The rows sit flush; the form keeps its blank row around the block.
+      rows = group do |g|
+        g.add(labelled("Name", Tuile::Component::TextField.new), Fixed[1])
+        g.add(labelled("Email", Tuile::Component::TextField.new), Fixed[1])
+        g.add(company, Fixed[1])
+        g.add(vat, Fixed[1])
+      end
+      apply.call
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(business, Fixed[1])
+        f.add(rows, Fixed[4])
+        f.add(status, Fixed[1])
+      end
+    end
+
     # One filterable log level: the item type a CheckboxGroup holds. Its `value`
     # is a Set of *these*, never of the labels shown on the rows.
     LogLevel = Data.define(:label, :tag, :color)
@@ -808,7 +1048,7 @@ module SamplerExample
       short_size = ->(bytes) { bytes < 1024 ? bytes.to_s : "#{(bytes / 1024.0).round}k" }
 
       update_status = lambda do
-        under_cursor = SORT_ORDERS[group.content.cursor.position]
+        under_cursor = SORT_ORDERS[group.list.cursor.position]
         status.text = "value: #{group.value.label} — cursor: #{under_cursor&.label}"
       end
       resort = lambda do
@@ -819,9 +1059,9 @@ module SamplerExample
       end
       resort.call
       group.on_value_change = ->(_order) { resort.call }
-      # `content` is the composed List, which is where the cursor lives.
+      # `list` is the composed List, which is where the cursor lives.
       # Watching it is what makes the chrome/value split visible above.
-      group.content.on_cursor_changed = ->(_idx, _line) { update_status.call }
+      group.list.on_cursor_changed = ->(_idx, _line) { update_status.call }
 
       # Side-by-side body on a rect-callback {Panel}, as in the CheckboxGroup
       # demo — the sidebar width is a capped proportion, not a constraint.