tuile 0.14.0 → 0.16.0

data/lib/tuile/screen_pane.rb

@@ -8,7 +8,7 @@ module Tuile
   # {#content} and the {#popups} stack. Putting them under a single Component
   # parent gives focus traversal a real root, makes {Component#attached?} a
   # one-liner, and lets popup-focus repair fall out of the standard
-  # {Component#on_child_removed} hook.
+  # {Component#handle_child_removed} hook.
   #
   # The pane owns no chrome of its own — no status bar, no reserved row.
   # {#content} gets the full pane rect, and an app that wants a status line
@@ -79,7 +79,7 @@ module Tuile
         window.center
         screen.focused = window
       end
-      window.on_tree { |c| screen.invalidate(c) }
+      window.walk_tree { |c| screen.invalidate(c) }
     end
 
     # Removes a popup. If the popup held focus, focus shifts to the now-topmost
@@ -102,7 +102,7 @@ module Tuile
       @removing_popup_prior = nil
     end
 
-    # Unmounts everything: each child is detached — firing {Component#on_detached}
+    # Unmounts everything: each child is detached — firing {Component#handle_detached}
     # down its subtree — and every slot is emptied. Terminal; the pane isn't
     # reusable afterwards, and {Screen#close} is its only caller.
     #
@@ -113,7 +113,7 @@ module Tuile
     # components, which is the desync the tree API exists to prevent.
     # @return [void]
     def detach_all
-      screen.focused = nil # …so the focus repair in on_child_removed has nothing to do
+      screen.focused = nil # …so the focus repair in handle_child_removed has nothing to do
       children.dup.each { detach_child(_1) }
       @content = nil
       @popups.clear
@@ -157,7 +157,7 @@ module Tuile
     def repaint; end
 
     # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
-    # the first component whose `handle_key` returns true wins.
+    # the first component whose `handle_key?` returns true wins.
     #
     # Bubbling stops at the *scope* root: the topmost *modal* popup when one is
     # open, else the tiled {#content}. Focus that is nil or sits outside the
@@ -173,44 +173,48 @@ module Tuile
     # hijacked).
     # @param key [String]
     # @return [Boolean] true if the key was handled.
-    def handle_key(key)
+    def handle_key?(key)
       scope = modal_popup || @content
       return false if scope.nil?
 
       bubble_key(key, scope)
     end
 
-    # Delivers pasted text along the same focus chain {#handle_key} bubbles
-    # along, and with the same scoping — first {Component#handle_paste}
-    # returning true wins.
+    # Delivers pasted text to {Screen#focused} — and to nobody else.
+    #
+    # Scoped exactly like {#handle_key?} (focus that is nil or sits outside the
+    # modal scope receives nothing, which is what keeps a popup modal) but
+    # **not bubbled**: an ancestor is never offered a paste its descendant
+    # declined, and unhandled text is dropped. Why keys bubble and pastes
+    # don't: `D_bracketed_paste`.
     # @param text [String]
-    # @return [Boolean] true if the text was consumed.
+    # @return [void]
     def handle_paste(text)
       scope = modal_popup || @content
-      return false if scope.nil?
+      return if scope.nil?
 
       chain = focus_chain(scope)
-      return false if chain.nil?
+      return if chain.nil?
 
-      chain.each { |c| return true if c.handle_paste(text) }
-      false
+      chain.first.handle_paste(text)
     end
 
-    # Mouse events check popups in reverse stacking order (topmost first), and
-    # fall through to content only when no popup is hit *and* no modal popup is
-    # open. This preserves modal click-blocking — an open modal eats clicks
-    # even outside its rect — while a non-modal overlay blocks nothing: clicks
-    # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
-    # content beneath.
-    #
-    # A left click also *dismisses* the open popups it landed outside of that
-    # asked for it ({Component::Overlay#close_on_outside_click?}). That is a
-    # second thing happening on a click, but not a second dispatch: the click is
-    # still delivered exactly once, down one chain, and a dismissed popup is
+    # Where {Mouse::Router} starts its walk for a pointer at `point`: the
+    # topmost popup containing it, else {#content} — unless a modal popup is
+    # open, which eats the event even outside its rect. A non-modal overlay
+    # blocks nothing: a point outside it reaches the content beneath.
+    # @api private
+    # @param point [Point]
+    # @return [Component, nil]
+    def mouse_root_at(point) = popup_at(point) || (@content if modal_popup.nil?)
+
+    # Runs the press delivery in the block, then *dismisses* the open popups a
+    # left press landed outside of that asked for it
+    # ({Component::Overlay#close_on_outside_click?}). A dismissed popup is
     # closed rather than told.
     #
     # "Outside" is measured against the {Component::Overlay#owner} chain, not
-    # against one rect and not against stacking order: the popup the click hit
+    # against one rect and not against stacking order: the popup the press hit
     # is kept, and so is every popup that one *belongs to*, transitively. That
     # is what stops a dialog being dismissed by a click on a dropdown its own
     # field opened, and a menu cascade being dismissed by a click on one of its
@@ -220,10 +224,10 @@ module Tuile
     #
     # Two halves of the ordering are load-bearing, and both are specced:
     #
-    # - **Snapshot before routing.** A popup the delivered click *opens* must
+    # - **Snapshot before the block.** A popup the delivered press *opens* must
     #   not be in the set (it would immediately dismiss itself — every
     #   {Component::Select} would be unopenable by mouse).
-    # - **Close after routing.** A widget toggling its own overlay from a click
+    # - **Close after the block.** A widget toggling its own overlay from a press
     #   on its face closes it during delivery, and {Component::Popup#close} is
     #   idempotent, so the dismissal no-ops. Close *first* and the widget sees
     #   a shut overlay and reopens it — a Select's dropdown could then never be
@@ -231,19 +235,19 @@ module Tuile
     #
     # The snapshot is a fresh array for a third reason: a handler may close
     # further popups, and `@popups` must not be mutated mid-iteration.
-    # @param event [MouseEvent]
+    # @api private
+    # @param point [Point]
+    # @param left [Boolean] whether the press was the left button; no other
+    #   button dismisses.
+    # @yield the press delivery.
     # @return [void]
-    def handle_mouse(event)
-      hit = @popups.reverse_each.find { _1.rect.contains?(event.point) }
-      dismissable = event.button == :left ? @popups - kept_by(hit) : []
-
-      clicked = hit || (@content if modal_popup.nil?)
-      clicked&.handle_mouse(event)
-
+    def dismissing_popups_outside(point, left:)
+      dismissable = left ? @popups - kept_by(popup_at(point)) : []
+      yield
       dismissable.each { _1.close if _1.close_on_outside_click? }
     end
 
-    # Focus repair when a child detaches. Default {Component#on_child_removed}
+    # Focus repair when a child detaches. Default {Component#handle_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
     # Instead, route focus to the first interactable widget in the now-topmost
     # modal popup; falling back to the focus snapshotted when this popup was opened
@@ -256,7 +260,7 @@ module Tuile
     # `q`/ESC still has somewhere to dispatch from.
     # @param child [Component]
     # @return [void]
-    def on_child_removed(child)
+    def handle_child_removed(child)
       return unless attached?
 
       f = screen.focused
@@ -298,6 +302,10 @@ module Tuile
       kept
     end
 
+    # @param point [Point]
+    # @return [Component::Overlay, nil] the topmost popup containing `point`.
+    def popup_at(point) = @popups.reverse_each.find { _1.rect.contains?(point) }
+
     # @param component [Component, nil]
     # @return [Component::Overlay, nil] `component` itself when it is an
     #   overlay, else the nearest overlay above it, else nil.
@@ -318,7 +326,7 @@ module Tuile
       chain = focus_chain(scope)
       return false if chain.nil?
 
-      chain.each { |c| return true if c.handle_key(key) }
+      chain.each { |c| return true if c.handle_key?(key) }
       false
     end
 
@@ -340,13 +348,14 @@ module Tuile
 
     # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling
     # back to `root` itself when the subtree has no tab stops. Returns `nil`
-    # if `root` is `nil`.
+    # if `root` is `nil`, or if `root` is itself hidden — there is nothing in
+    # there to focus, so the caller falls through to its next candidate.
     # @param root [Component, nil]
     # @return [Component, nil]
     def first_tab_stop_or_root(root)
-      return nil if root.nil?
+      return nil if root.nil? || !root.visible?
 
-      root.on_tree { |c| return c if c.tab_stop? }
+      root.walk_shown_tree { |c| return c if c.tab_stop? }
       root
     end
   end

data/lib/tuile/styled_string.rb

@@ -410,11 +410,11 @@ module Tuile
     #
     # `:rgi` credits width 2 only to [RGI](https://www.unicode.org/reports/tr51/)
     # sequences — the ones vendors actually ship a single glyph for — and *sums*
-    # the parts of anything else. That is the one setting never wrong in the
-    # dangerous direction: under-measuring lets a glyph overrun its cell, which
-    # shifts the rest of the row, desyncs the cursor and escapes the component's
-    # rect, while over-measuring leaves a blank column. `D_cluster_width` has the
-    # per-setting reasoning.
+    # the parts of anything else, erring only in the direction that cannot escape
+    # a component: {Buffer#flush} emits a dirty run contiguously, so a mis-measure
+    # of either sign shifts the rest of that run, but only an under-measure shifts
+    # it right, into a neighbour whose cells are clean and so never repainted.
+    # `D_cluster_width` has the per-setting reasoning.
     # @return [Symbol]
     EMOJI_WIDTH = :rgi
 

data/lib/tuile/testing.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Finds a component in the tree, so a spec can drive the UI it built four
+  # layers down:
+  #
+  #   Testing.get(Component::Button, caption: "Save").handle_key?(Keys::ENTER)
+  #   Testing.get(id: :name).value = "Zaphod"
+  #   Testing.find(Component::Checkbox, in: pane, count: 3)
+  #
+  # {.get} demands exactly one match and raises with a {.dump} of the tree it
+  # searched; {.find} returns every match and takes an optional `count:`. Both
+  # search {Screen}'s whole tree by default — popups included, since they live
+  # under the same {ScreenPane} as the content — or the subtree given as `in:`.
+  #
+  # **Call these qualified**, as above: `find` and `get` collide with names a
+  # spec suite is likely to have already (Capybara's `find`), so there is no
+  # `Component#get` and mixing this module in is not recommended. Tuile's own
+  # specs sit inside `module Tuile` and so need no include.
+  #
+  # **A hidden component is never found**: these simulate a user, and a spec
+  # that drove a hidden {Component::Button} would pass against a form nobody
+  # can operate. Both walk {Component#walk_shown_tree}; a failed lookup says how
+  # many hidden components *would* have matched, and {.dump} shows them.
+  #
+  #   Testing.find(Component::TextField, count: 0)   # the user can't reach it
+  #   refute field.visible?                          # it is hidden
+  #
+  # There is deliberately no `visible:` filter handing one back to drive
+  # (`D_visibility`).
+  #
+  # For *what a component shows*, assert on {Screen#buffer} instead — this
+  # locates and drives, it does not replace that channel. See book ch8 for the
+  # worked usage and `design/decisions.md` `D_component_lookup` for the design.
+  module Testing
+    # Raised when the match count is not the one asked for. A {Tuile::Error},
+    # so an app rescuing that still catches it.
+    class LookupError < Error; end
+
+    class << self
+      # Every component in the searched tree matching the spec, in pre-order.
+      #
+      #   find(Component::Button)                     # every button on screen
+      #   find(Component::HasBadInput, in: form)      # a mixin works too
+      #   find(Component::Label, caption: /^Total/)   # Regexp: partial match
+      #   find(Component::Popup, count: 1..)          # assert at least one
+      #
+      # @param klass [Module] matched with `is_a?`, so a mixin
+      #   ({Component::HasValue}) finds every field that includes it.
+      # @param in [Component, nil] root of the subtree to search, itself
+      #   included. Defaults to `Screen.instance.pane` — the whole UI.
+      # @param id [Symbol, nil] matched against {Component#id}.
+      # @param caption [String, Regexp, nil] matched with `===` against
+      #   {Component::HasCaption#caption}`.to_s`, so a String is exact and a
+      #   Regexp is a partial match. Never matches a component without a
+      #   caption.
+      # @param count [Integer, Range, nil] how many matches are expected; any
+      #   number when nil.
+      # @yield [component] optional extra predicate; a component matches only
+      #   when the block returns truthy.
+      # @yieldparam component [Component]
+      # @yieldreturn [Boolean]
+      # @raise [LookupError] if `count` is given and the match count differs.
+      # @return [Array<Component>]
+      def find(klass = Component, in: nil, id: nil, caption: nil, count: nil, &predicate)
+        # `in` is a Ruby keyword, so the local it binds is unreachable by name.
+        scope = binding.local_variable_get(:in) || Screen.instance.pane
+        spec = ->(c) { matches_spec?(c, klass, id, caption, predicate) }
+        matches = []
+        scope.walk_shown_tree { |c| matches << c if spec.call(c) }
+        return matches if count.nil? || spec_match?(count, matches.size)
+
+        raise LookupError, failure(klass, id, caption, predicate, count, matches, scope, spec)
+      end
+
+      # The one component matching the spec — {.find} with `count: 1`, so it
+      # raises rather than returning nil, and raises on an ambiguous spec too.
+      #
+      #   get(Component::ComboBox, in: sampler.demo_window)
+      #
+      # @param klass [Module] see {.find}.
+      # @param in [Component, nil] see {.find}.
+      # @param id [Symbol, nil] see {.find}.
+      # @param caption [String, Regexp, nil] see {.find}.
+      # @yield [component] see {.find}.
+      # @yieldparam component [Component]
+      # @yieldreturn [Boolean]
+      # @raise [LookupError] unless exactly one component matches.
+      # @return [Component]
+      def get(klass = Component, in: nil, id: nil, caption: nil, &predicate)
+        scope = binding.local_variable_get(:in)
+        find(klass, in: scope, id:, caption:, count: 1, &predicate).first
+      end
+
+      # The searched tree, one component per row, indented by depth and with
+      # the `Tuile::` namespaces stripped so a fifty-row dump stays readable
+      # (an app's own component classes keep their full name):
+      #
+      #     #<ScreenPane rect=(0,0 160x50)>
+      #       #<Window rect=(0,0 40x10) caption="Settings">
+      #         #<Layout::Vertical rect=(1,1 38x8)>
+      #   →       #<Button id=:save rect=(1,1 38x1) caption="Save">
+      #
+      # @param scope [Component] root of the tree to dump.
+      # @param marked [Array<Component>] components to flag with a leading
+      #   arrow — the matches, when a lookup found the wrong number of them.
+      # @param excluded [Array<Component>] components to flag with `⊘` — ones
+      #   that matched the spec but were skipped for being hidden.
+      # @return [String]
+      def dump(scope, marked = [], excluded = [])
+        base = scope.depth
+        rows = []
+        # walk_tree, not walk_shown_tree: a reader looks here to find out where
+        # their component went, so the ones the search skipped are the point.
+        scope.walk_tree do |c|
+          mark = if marked.any? { _1.equal?(c) } then "→"
+                 elsif excluded.any? { _1.equal?(c) } then "⊘"
+                 else " "
+                 end
+          row = c.inspect.sub("#<Tuile::Component::", "#<").sub("#<Tuile::", "#<")
+          rows << "#{mark} #{"  " * (c.depth - base)}#{row}"
+        end
+        rows.join("\n")
+      end
+
+      private
+
+      # @param component [Component]
+      # @param klass [Module] see {.find}.
+      # @param id [Symbol, nil] see {.find}.
+      # @param caption [String, Regexp, nil] see {.find}.
+      # @param predicate [Proc, nil] see {.find}.
+      # @return [Boolean] whether the component satisfies every given term.
+      #   Visibility is the *walk's* business, deliberately not tested here, so
+      #   {.failure} can re-run this over the components the walk skipped.
+      def matches_spec?(component, klass, id, caption, predicate)
+        return false unless component.is_a?(klass)
+        return false unless id.nil? || component.id == id
+        if !caption.nil? &&
+           !(component.is_a?(Component::HasCaption) && spec_match?(caption, component.caption.to_s))
+          return false
+        end
+
+        predicate.nil? || predicate.call(component)
+      end
+
+      # Whether `actual` satisfies a spec value, which for both `caption:` and
+      # `count:` may be either an exact value or a pattern — `===` is the
+      # feature, not an accident: a String caption matches exactly and a Regexp
+      # partially, an Integer count exactly and a Range as a bound.
+      # @param spec [Object] the expected value or pattern.
+      # @param actual [Object]
+      # @return [Boolean]
+      def spec_match?(spec, actual) = spec === actual # rubocop:disable Style/CaseEquality
+
+      # @param klass [Module] the class or mixin that was asked for.
+      # @param id [Symbol, nil] the id spec, if any.
+      # @param caption [String, Regexp, nil] the caption spec, if any.
+      # @param predicate [Proc, nil] the block spec, if any.
+      # @param count [Integer, Range] the count that was not met.
+      # @param matches [Array<Component>] what the search did find.
+      # @param scope [Component] the root that was searched.
+      # @param spec [Proc] the same term test the search ran, re-run over the
+      #   components the walk skipped.
+      # @return [String]
+      def failure(klass, id, caption, predicate, count, matches, scope, spec)
+        wanted = [(klass.name || klass.to_s).sub("Tuile::", "")]
+        wanted << "id=#{id.inspect}" unless id.nil?
+        wanted << "caption=#{caption.inspect}" unless caption.nil?
+        wanted << "matching the block" unless predicate.nil?
+        excluded = hidden_matches(scope, spec)
+        "expected #{count} #{wanted.join(" ")}, found #{matches.size}#{excluded_note(excluded)}\n" \
+          "searched:\n#{dump(scope, matches, excluded)}"
+      end
+
+      # The components that satisfy the spec but were skipped for being hidden
+      # — the answer to the "but it *is* there" a failed lookup provokes.
+      # @param scope [Component] the root that was searched.
+      # @param spec [Proc] the term test.
+      # @return [Array<Component>]
+      def hidden_matches(scope, spec)
+        shown = Set.new
+        scope.walk_shown_tree { shown << _1 }
+        hidden = []
+        scope.walk_tree { |c| hidden << c if !shown.include?(c) && spec.call(c) }
+        hidden
+      end
+
+      # @param excluded [Array<Component>] see {.hidden_matches}.
+      # @return [String] the clause naming them, or "" when there were none.
+      def excluded_note(excluded)
+        return "" if excluded.empty?
+
+        " (#{excluded.size} hidden #{excluded.size == 1 ? "match" : "matches"} excluded)"
+      end
+    end
+  end
+end

data/lib/tuile/theme.rb

@@ -7,12 +7,12 @@ module Tuile
   # restyles everything via one invalidate-everything pass. Book ch6 is the
   # concept in full (why accents-only, dark/light, live OS flips).
   #
-  # The rendering helpers — {#active_bg}, {#active_border}, {#input_bg},
-  # {#hint} — wrap a plain string in the token's SGR color (on the channel
-  # appropriate for the token's role) and reset:
+  # The rendering helpers — {#active_bg}, {#active_border}, {#input_bg} — wrap
+  # a plain string in the token's SGR color (on the channel appropriate for the
+  # token's role) and reset:
   #
-  #   screen.theme.active_bg("[ Ok ]")   # => "\e[48;5;59m[ Ok ]\e[0m"
-  #   screen.theme.hint("quit")          # => "\e[38;5;109mquit\e[0m"
+  #   screen.theme.active_bg("[ Ok ]")       # => "\e[48;5;59m[ Ok ]\e[0m"
+  #   screen.theme.active_border("┌────┐")   # => "\e[32m┌────┐\e[0m"
   #
   # Content passes through verbatim (so it may carry other escapes). For
   # span-aware styling — a token applied to a {StyledString} without flattening
@@ -44,7 +44,7 @@ module Tuile
   #
   # For a color slot resolved *live* at paint — currently
   # {Component#bg_color=} — assign a {Ref} instead of reading + rebuilding
-  # the token in {Component#on_theme_changed}; it tracks theme swaps on its
+  # the token in {Component#handle_theme_changed}; it tracks theme swaps on its
   # own. Baked content colors ({Component::Label} text and friends) can't:
   # they live in a frozen {StyledString} and still need the hook.
   #
@@ -64,9 +64,32 @@ module Tuile
   #   {Component::TextArea} when *not* active — visibly a field, but
   #   distinctly subtler than {#active_bg_color}.
   #   @return [Color]
-  # @!attribute [r] hint_color
-  #   Foreground of keyboard-shortcut captions in status-bar hints (the
-  #   "quit" in "q quit") — see {#hint}.
+  # @!attribute [r] placeholder_color
+  #   Foreground of the hint a field paints into its own empty well
+  #   ({Component::HasPlaceholder}) — the one token tuned to be *barely*
+  #   visible, since a placeholder the user misses costs nothing.
+  #   @return [Color]
+  # @!attribute [r] error_color
+  #   Foreground for the *message* beside an invalid field — the text a
+  #   container paints from {Component::HasValidation#error_message}. The
+  #   field's own face uses {#error_bg_color} instead.
+  #   @return [Color]
+  # @!attribute [r] error_bg_color
+  #   Resting well of a field that is invalid — {#input_bg_color}'s red
+  #   counterpart, and the reason the pair exists rather than one flat error
+  #   color: a field's well is what shows its boundary, so an invalid field
+  #   needs a well *and* still needs to show focus.
+  #   @return [Color]
+  # @!attribute [r] error_active_bg_color
+  #   Well of an invalid field that also has focus — {#active_bg_color}'s red
+  #   counterpart. Must stay distinguishable from {#error_bg_color} after
+  #   {Color#quantize}, or a focused invalid {Component::Select} (which paints
+  #   no caret) shows no focus at all.
+  #   @return [Color]
+  # @!attribute [r] scrollbar_color
+  #   Foreground of the {VerticalScrollBar} a {Component::List} or
+  #   {Component::TextView} paints down its right edge — handle and track
+  #   alike, which the glyphs' own ink densities tell apart.
   #   @return [Color]
   # @!attribute [r] custom
   #   App-specific color tokens; empty in the built-in themes. Frozen —
@@ -74,16 +97,24 @@ module Tuile
   #   lookups (it fail-fasts on typos); read this directly to enumerate
   #   the tokens.
   #   @return [Hash{Symbol => Color}]
-  class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color, :hint_color, :custom)
+  class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
+                            :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
+                            :scrollbar_color, :custom)
     # @param active_bg_color [Color]
     # @param active_border_color [Color]
     # @param input_bg_color [Color]
-    # @param hint_color [Color]
+    # @param placeholder_color [Color]
+    # @param error_color [Color]
+    # @param error_bg_color [Color]
+    # @param error_active_bg_color [Color]
+    # @param scrollbar_color [Color]
     # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
     # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
     #   `Hash{Symbol => Color}`.
-    def initialize(active_bg_color:, active_border_color:, input_bg_color:, hint_color:, custom: {})
-      { active_bg_color:, active_border_color:, input_bg_color:, hint_color: }.each do |name, value|
+    def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
+                   error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
+      { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
+        error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
         raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
       end
       raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)
@@ -92,7 +123,8 @@ module Tuile
         raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
         raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
       end
-      super(active_bg_color:, active_border_color:, input_bg_color:, hint_color:, custom: custom.dup.freeze)
+      super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
+            error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
     end
 
     # Looks up an app-specific token from {#custom}.
@@ -123,7 +155,7 @@ module Tuile
     # A live reference to a theme token, resolved against the current theme at
     # paint time rather than baked to a concrete {Color}. Assign one where a
     # slot is resolved late — currently {Component#bg_color=} — and it follows
-    # light/dark flips with no {Component#on_theme_changed} hook:
+    # light/dark flips with no {Component#handle_theme_changed} hook:
     #
     #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
     #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
@@ -155,7 +187,14 @@ module Tuile
     end
 
     # Renders `text` in the foreground color of the app-specific `token`
-    # — the generic counterpart of {#hint} for {#custom} tokens.
+    # — the generic counterpart of {#active_border} for {#custom} tokens, and
+    # the route for an app's own status-line chrome:
+    #
+    #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
+    #
+    # The color is baked into the returned String, so text built this way does
+    # *not* restyle on a {Screen#theme=} — rebuild it from
+    # {Component#handle_theme_changed} instead.
     # @param token [Symbol]
     # @param text [String]
     # @return [String] ANSI-rendered text, ending with an SGR reset.
@@ -187,40 +226,79 @@ module Tuile
     # @return [String] ANSI-rendered text, ending with an SGR reset.
     def input_bg(text) = wrap(text, input_bg_color, :bg)
 
-    # Renders `text` in the {#hint_color} foreground, for status-bar hints,
-    # e.g. `"q #{screen.theme.hint("quit")}"`. The color is baked into the
-    # returned String, so strings built this way do *not* restyle when the
-    # theme changes — rebuild them instead (the framework's own call sites
-    # rebuild on every status-bar refresh).
-    # @param text [String]
-    # @return [String] ANSI-rendered text, ending with an SGR reset.
-    def hint(text) = wrap(text, hint_color, :fg)
-
     # The colors Tuile used before themes existed, tuned for dark terminal
     # backgrounds. GREY37 (palette 59) is what Rainbow emits for
-    # `:darkslategray`, LIGHT_SKY_BLUE3 (109) for `:cadetblue`; GREY27
+    # `:darkslategray`; GREY27
     # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
     # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
     # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
-    # darker than the active highlight at 59 (~#5f5f5f).
+    # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
+    # GREY37, giving the handle the weight of the selection well and leaving
+    # the sparser track glyph near-invisible.
+    #
+    # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
+    # (196): the message sits beside a field on the terminal's own background,
+    # and the softer red keeps its contrast there while pure red vibrates.
+    #
+    # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
+    # — split on lightness the way GREY27/GREY37 are, so the focused one is the
+    # *lighter* well and the pair reads as a well rather than an alarm block.
+    # Both survive `palette256` as themselves and stay distinct from each other
+    # there, which is what keeps focus visible on an invalid field. The focused
+    # well stays out of the bright mid-reds around #af5f5f: that is where
+    # terminals put the cursor, and a caret sitting in an invalid field blurs
+    # into a well of its own color.
+    #
+    # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
+    # own foreground, so an empty field's hint reads as absent-value rather than
+    # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
+    # a 16-color terminal — everything below 248 lands on `:bright_black`
+    # alongside both wells, where the hint is not subtle but gone
+    # (`design/decisions.md` `D_placeholder`).
     # @return [Theme]
     DARK = new(active_bg_color: Color::GREY37,
                active_border_color: Color::GREEN,
                input_bg_color: Color::GREY27,
-               hint_color: Color::LIGHT_SKY_BLUE3)
+               placeholder_color: Color::GREY66,
+               error_color: Color::INDIAN_RED1,
+               error_bg_color: Color.palette(88),
+               error_active_bg_color: Color::LIGHT_PINK4,
+               scrollbar_color: Color::GREY37)
 
     # Counterparts legible on light terminal backgrounds: grayscale-ramp
     # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
     # ~#dadada — dark enough to read as a "well" against white, one step
-    # lighter than the active highlight) and a dark teal (TURQUOISE4 = 30,
-    # ~#008787) keeping the hint hue. `active_border_color` stays the
+    # lighter than the active highlight). `active_border_color` stays the
     # named green — named ANSI colors are remapped by the terminal's own
-    # palette, so the theme picks a light-appropriate green for us.
+    # palette, so the theme picks a light-appropriate green for us. GREY62
+    # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
+    # goes a step darker than the highlights rather than matching them. RED3
+    # (124, ~#af0000) is the error ink, dark for the same reason — the light
+    # red {DARK} uses would wash out on white.
+    #
+    # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
+    # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
+    # weight, and darken on focus as the grey pair does. 224 is the palest red
+    # the 256-color palette holds: anything subtler quantizes onto the grey ramp
+    # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
+    # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
+    # so an invalid field reads level with a valid one rather than more
+    # recessed — the price of staying close to a white background.
+    #
+    # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
+    # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
+    # 16-color terminal, where both light wells are `:white`. It doubles as the
+    # scrollbar ink, which wants the same thing — a foreground that recedes
+    # against pale without vanishing into it.
     # @return [Theme]
     LIGHT = new(active_bg_color: Color::GREY82,
                 active_border_color: Color::GREEN,
                 input_bg_color: Color::GREY85,
-                hint_color: Color::TURQUOISE4)
+                placeholder_color: Color::GREY62,
+                error_color: Color::RED3,
+                error_bg_color: Color::MISTY_ROSE1,
+                error_active_bg_color: Color::LIGHT_PINK1,
+                scrollbar_color: Color::GREY62)
 
     private
 

data/lib/tuile/version.rb

@@ -2,5 +2,5 @@
 
 module Tuile
   # @return [String]
-  VERSION = "0.14.0"
+  VERSION = "0.16.0"
 end