tuile 0.9.0 → 0.11.0

data/lib/tuile/styled_string.rb

@@ -3,14 +3,11 @@
 module Tuile
   # An immutable string-with-styling, modeled as a sequence of {Span}s where
   # each span carries a complete {Style} (`fg`, `bg`, `bold`, `italic`,
-  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile the string — every
-  # character has exactly one resolved style, no overlay layers to merge.
-  #
-  # Where this differs from threading SGR escapes through a plain `String`:
-  # slicing, wrapping, and concatenation operate on the structured spans, so
-  # they never have to "figure out what SGR state is active at column N" —
-  # the answer is just the containing span's `style`. The flip side is one
-  # extra type to construct (or parse) before doing styled-text math.
+  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile
+  # the string — every character has exactly one resolved style, no overlay
+  # layers to merge, so the style at any column is just its span's `style`
+  # rather than a replay of the SGR state machine. The book's chapter 9 is
+  # the long-form *why* (spans vs. a `String` full of escape codes).
   #
   # ## Constructors
   #
@@ -34,30 +31,15 @@ module Tuile
   # ss.each_char_with_style { |ch, style| ... }
   # ```
   #
-  # ## Rendering
-  #
-  # - `#to_s` — plain text, no SGR.
-  # - `#to_ansi` — minimal-diff SGR rendering, ending with `\e[0m` only when
-  #   the last span carried a non-default style. Transitions to the default
-  #   style emit `\e[0m` (shorter than re-emitting every off-code).
-  #
   # ## Parser
   #
-  # {.parse} is strict by default: it recognizes only the SGR codes
-  # corresponding to {Style}'s supported attributes (fg/bg/bold/italic/
-  # underline/strikethrough). Anything else — unmodeled attributes (dim, blink,
-  # reverse, conceal, double-underline, overline, ...), unknown SGR codes, or
-  # non-SGR escapes (cursor moves, OSC) — raises {ParseError}. This keeps the
-  # round-trip parse(to_ansi(x)) == x contract honest.
-  #
-  # Pass `lenient: true` to instead **discard** everything the parser can't
-  # model and keep going — recognized fg/bg/bold/italic/underline/strikethrough codes still
-  # apply, and any unmodeled SGR code, malformed extended color, non-SGR CSI
-  # (cursor moves, `\e[K`), OSC/DCS/string sequence, or stray escape is
-  # silently dropped. This is the mode for piping in colored output you don't
-  # control (e.g. `git --color` through a pager): "give me the colors, throw
-  # the rest away." It is lossy by design — `parse(x, lenient: true)` does not
-  # round-trip back to `x`.
+  # {.parse} is strict by default — it recognizes only the SGR codes for
+  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough) and
+  # raises {ParseError} on anything else, keeping the `parse(to_ansi(x)) == x`
+  # round-trip honest. Pass `lenient: true` to instead discard everything it
+  # can't model (unmodeled SGR, cursor moves, OSC/DCS, stray escapes) and keep
+  # only the recognized colors — lossy by design, for piping in colored output
+  # you don't control. See the book for the full rationale.
   class StyledString
     # Raised by {.parse} on malformed or unsupported escape sequences.
     class ParseError < Error; end
@@ -111,10 +93,6 @@ module Tuile
       # `""` when the styles are identical (nothing to do), and {Ansi::RESET}
       # (`\e[0m`, one code) when `other` is the default style — shorter than
       # turning each attribute off individually.
-      #
-      # Shared by {StyledString#to_ansi} (diffing span-to-span from the default
-      # style) and {Buffer}'s flush (diffing cell-to-cell against the style the
-      # terminal currently holds), so both emit identical minimal sequences.
       # @param other [Style] the style to transition to.
       # @return [String]
       def sgr_to(other)
@@ -419,6 +397,19 @@ module Tuile
       end
     end
 
+    # The framework's single emoji-width policy, passed to every
+    # `Unicode::DisplayWidth.of` call in 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.
+    # @return [Symbol]
+    EMOJI_WIDTH = :rgi
+
     # @return [Array<Span>] the frozen, normalized span list — no empty-text
     #   entries, no two adjacent entries sharing a style.
     attr_reader :spans
@@ -430,10 +421,9 @@ module Tuile
 
     # Total display width in terminal columns, accounting for Unicode wide
     # characters (fullwidth CJK = 2 columns, combining marks = 0, etc.).
-    # Memoized — safe because spans are frozen and immutable.
     # @return [Integer]
     def display_width
-      @display_width ||= @spans.sum { |s| Unicode::DisplayWidth.of(s.text) }
+      @display_width ||= @spans.sum { |s| Unicode::DisplayWidth.of(s.text, emoji: EMOJI_WIDTH) }
     end
 
     # @return [Boolean]
@@ -450,7 +440,7 @@ module Tuile
     # emits `\e[0m` (one code) instead of the longer "turn each attribute
     # off" form. Always closes with `\e[0m` when the last span carried a
     # non-default style, so the styled run doesn't bleed into subsequent
-    # output. Memoized — safe because spans are frozen and immutable.
+    # output.
     # @return [String]
     def to_ansi
       @to_ansi ||= build_ansi
@@ -552,11 +542,20 @@ module Tuile
     # wrapped continuations, hard `"\n"` breaks preserved as separate output
     # lines.
     #
+    # An indent is content, so it survives onto the first row — but there is no
+    # hanging indent:
+    #
+    #   StyledString.plain("  read config").wrap(20).map(&:to_s)
+    #   # => ["  read config"]        indent kept; the line never wrapped
+    #   StyledString.plain("  read config").wrap(6).map(&:to_s)
+    #   # => ["  read", "config"]     ...but a continuation starts at column 0
+    #
     # Whitespace runs are space or tab; other characters are treated as word
     # content. When a single character is wider than `width` (e.g. a 2-column
     # CJK character with `width = 1`), it is still emitted on its own line at
     # its natural width. The "no line exceeds `width`" guarantee therefore
-    # holds whenever every character is at most `width` columns wide.
+    # holds whenever every character is at most `width` columns wide. An indent
+    # that alone exceeds `width` is dropped rather than given a row of its own.
     #
     # @param width [Integer, nil] target column width. `nil` or `<= 0` skips
     #   wrapping and returns each hard-line as-is, so callers can pass a
@@ -600,6 +599,24 @@ module Tuile
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bg: bg)) })
     end
 
+    # Returns a copy with `bg` set **only on spans that have none**; a span with
+    # an explicit bg is left untouched. The fill-unset counterpart of {#with_bg}
+    # (which overrides every span) — it slides a background *under* the content,
+    # so a log line keeps its red error-level bg while its plain text picks up an
+    # inherited panel tint.
+    #
+    # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background color,
+    #   coerced via {Color.coerce}. `nil` returns `self` unchanged.
+    # @return [StyledString]
+    def under_bg(bg)
+      return self if bg.nil?
+
+      bg = Color.coerce(bg)
+      self.class.new(@spans.map do |span|
+        span.style.bg.nil? ? Span.new(text: span.text, style: span.style.merge(bg: bg)) : span
+      end)
+    end
+
     # Returns a new {StyledString} with `fg` applied to every span, preserving
     # each span's text and other style attributes (`bg`, `bold`, `italic`,
     # `underline`, `strikethrough`). The new fg overlays without dropping background colors or
@@ -683,7 +700,7 @@ module Tuile
       out = []
       col = 0
       @spans.each do |span|
-        span_width = Unicode::DisplayWidth.of(span.text)
+        span_width = Unicode::DisplayWidth.of(span.text, emoji: EMOJI_WIDTH)
         span_end = col + span_width
 
         next col = span_end if span_end <= start
@@ -707,74 +724,93 @@ module Tuile
       return [hard_line] if hard_line.empty?
 
       result = []
-      line_chars = []
+      line_glyphs = []
       line_w = 0
 
-      tokenize_for_wrap(hard_line).each do |type, chars, w|
+      tokenize_for_wrap(hard_line).each do |type, glyphs, w|
         if type == :space
-          if line_w.zero?
-            # leading whitespace on a wrapped continuation: drop
+          if line_w.zero? && (!result.empty? || w > width)
+            # Nothing to emit: a continuation's leading run was consumed by the
+            # break, and an indent wider than the viewport conveys no nesting.
           elsif line_w + w <= width
-            line_chars.concat(chars)
+            line_glyphs.concat(glyphs)
             line_w += w
           else
-            result << chars_to_styled(line_chars)
-            line_chars = []
+            result << glyphs_to_styled(line_glyphs)
+            line_glyphs = []
             line_w = 0
           end
         elsif line_w + w <= width
-          line_chars.concat(chars)
+          line_glyphs.concat(glyphs)
           line_w += w
         elsif w > width
-          result << chars_to_styled(line_chars) unless line_w.zero?
-          chunks = hard_break_chars(chars, width)
-          chunks[0..-2].each { |chunk| result << chars_to_styled(chunk) }
-          line_chars = chunks.last
-          line_w = line_chars.sum { |triple| triple[2] }
+          result << glyphs_to_styled(line_glyphs) unless line_w.zero?
+          chunks = hard_break_glyphs(glyphs, width)
+          chunks[0..-2].each { |chunk| result << glyphs_to_styled(chunk) }
+          line_glyphs = chunks.last
+          line_w = line_glyphs.sum { |triple| triple[2] }
         else
-          result << chars_to_styled(line_chars)
-          line_chars = chars
+          result << glyphs_to_styled(line_glyphs)
+          line_glyphs = glyphs
           line_w = w
         end
       end
-      result << chars_to_styled(line_chars)
+      result << glyphs_to_styled(line_glyphs)
       result
     end
 
+    # Splits into whitespace/word tokens by **grapheme cluster**, not character:
+    # a cluster is the unit a terminal draws, so measuring its parts separately
+    # would both mis-total an emoji sequence and let a wrap break a letter away
+    # from its combining mark.
     # @param hard_line [StyledString]
-    # @return [Array<Array>] tokens shaped `[type, chars, w]` where `type` is
-    #   `:space` or `:word`, `chars` is an `Array<[String, Style, Integer]>`
-    #   (char, style, display width), and `w` is the token's total width.
+    # @return [Array<Array>] tokens shaped `[type, glyphs, w]` where `type` is
+    #   `:space` or `:word`, `glyphs` is an `Array<[String, Style, Integer]>`
+    #   (grapheme cluster, style, display width), and `w` is the token's total
+    #   width.
     def tokenize_for_wrap(hard_line)
       tokens = []
-      current_chars = []
+      current_glyphs = []
       current_w = 0
       current_type = nil
 
-      hard_line.each_char_with_style do |c, s|
-        type = [" ", "\t"].include?(c) ? :space : :word
-        cw = Unicode::DisplayWidth.of(c)
+      each_glyph_with_style(hard_line) do |g, s|
+        type = [" ", "\t"].include?(g) ? :space : :word
+        gw = Buffer.display_width(g)
         if current_type && current_type != type
-          tokens << [current_type, current_chars, current_w]
-          current_chars = []
+          tokens << [current_type, current_glyphs, current_w]
+          current_glyphs = []
           current_w = 0
         end
         current_type = type
-        current_chars << [c, s, cw]
-        current_w += cw
+        current_glyphs << [g, s, gw]
+        current_w += gw
       end
-      tokens << [current_type, current_chars, current_w] unless current_chars.empty?
+      tokens << [current_type, current_glyphs, current_w] unless current_glyphs.empty?
       tokens
     end
 
-    # @param chars [Array<Array>] `[char, style, width]` triples.
+    # Like {#each_char_with_style} but per grapheme cluster. A cluster spanning a
+    # style boundary takes the style of its first span — pathological input, and
+    # splitting the cluster to honor both styles would paint a headless mark.
+    # @param styled [StyledString]
+    # @yieldparam glyph [String] one grapheme cluster.
+    # @yieldparam style [Style]
+    # @return [void]
+    def each_glyph_with_style(styled)
+      styled.spans.each do |span|
+        span.text.each_grapheme_cluster { |g| yield g, span.style }
+      end
+    end
+
+    # @param glyphs [Array<Array>] `[grapheme cluster, style, width]` triples.
     # @param width [Integer]
-    # @return [Array<Array<Array>>] each inner Array is a `chars`-shaped chunk.
-    def hard_break_chars(chars, width)
+    # @return [Array<Array<Array>>] each inner Array is a `glyphs`-shaped chunk.
+    def hard_break_glyphs(glyphs, width)
       chunks = []
       current = []
       current_w = 0
-      chars.each do |triple|
+      glyphs.each do |triple|
         cw = triple[2]
         if current_w + cw > width && current_w.positive?
           chunks << current
@@ -788,20 +824,20 @@ module Tuile
       chunks
     end
 
-    # @param chars [Array<Array>] `[char, style, width]` triples.
+    # @param glyphs [Array<Array>] `[grapheme cluster, style, width]` triples.
     # @return [StyledString]
-    def chars_to_styled(chars)
-      return self.class.new if chars.empty?
+    def glyphs_to_styled(glyphs)
+      return self.class.new if glyphs.empty?
 
       spans = []
       current_text = +""
-      current_style = chars.first[1]
-      chars.each do |c, s, _|
+      current_style = glyphs.first[1]
+      glyphs.each do |g, s, _|
         if s == current_style
-          current_text << c
+          current_text << g
         else
           spans << Span.new(text: current_text, style: current_style)
-          current_text = +c
+          current_text = +g
           current_style = s
         end
       end
@@ -809,6 +845,9 @@ module Tuile
       self.class.new(spans)
     end
 
+    # Walks **grapheme clusters**, so a slice boundary can never fall inside one:
+    # cutting a cluster would strand a combining mark with no base, which the
+    # painter drops outright, silently losing the accent off a letter.
     # @param text [String]
     # @param start_col [Integer]
     # @param len_col [Integer]
@@ -816,18 +855,18 @@ module Tuile
     def slice_text_by_columns(text, start_col, len_col)
       out = +""
       col = 0
-      text.each_char do |c|
-        cw = Unicode::DisplayWidth.of(c)
-        char_end = col + cw
-        if char_end <= start_col
+      text.each_grapheme_cluster do |g|
+        gw = Buffer.display_width(g)
+        glyph_end = col + gw
+        if glyph_end <= start_col
           # entirely before slice — skip
         elsif col >= start_col + len_col
           break
-        elsif col >= start_col && char_end <= start_col + len_col
-          out << c
+        elsif col >= start_col && glyph_end <= start_col + len_col
+          out << g
         end
-        # any other case = partial overlap with a wide char — drop
-        col = char_end
+        # any other case = partial overlap with a wide glyph — drop
+        col = glyph_end
       end
       out
     end

data/lib/tuile/theme.rb

@@ -1,67 +1,52 @@
 # frozen_string_literal: true
 
 module Tuile
-  # A set of semantic colors the built-in components read when painting.
-  # The current theme lives at {Screen#theme}; components must look it up
-  # at paint time (inside `repaint`) rather than caching values, so that
-  # assigning {Screen#theme=} restyles everything via a single
-  # invalidate-everything pass.
+  # A set of semantic colors the built-in components read when painting. The
+  # current theme lives at {Screen#theme}; components must look it up at paint
+  # time (inside `repaint`) rather than caching values, so a {Screen#theme=}
+  # restyles everything via one invalidate-everything pass. Book ch6 is the
+  # concept in full (why accents-only, dark/light, live OS flips).
   #
-  # The primary API is the rendering helpers — {#active_bg},
-  # {#active_border}, {#input_bg}, {#hint} — which 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},
+  # {#hint} — 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"
   #
-  # The helpers pass content through verbatim, so input may carry other
-  # escape sequences (e.g. {Component::Window} feeds its border string,
-  # cursor moves included). For span-aware styling — applying a token to a
-  # {StyledString} while preserving per-span colors — use the `*_color`
-  # readers instead (e.g. {Component::List} highlights its cursor row via
-  # `with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome text →
-  # helper; structured text → `*_color` reader + {StyledString}.
+  # Content passes through verbatim (so it may carry other escapes). For
+  # span-aware styling — a token applied to a {StyledString} without flattening
+  # its per-span colors — use the `*_color` readers instead
+  # (`with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome → helper;
+  # structured text → `*_color` reader + {StyledString}.
   #
-  # Two built-in themes are provided: {DARK} (the default; the colors Tuile
-  # has always used) and {LIGHT} (counterparts legible on light terminal
-  # backgrounds). A custom theme is one `with` away:
+  # Two built-in themes ship: {DARK} (default) and {LIGHT}. A custom one is one
+  # `with` away, and every token must be a {Color} instance — not the lenient
+  # {Color.coerce} forms, since a theme is declared once so the verbosity
+  # self-documents:
   #
   #   screen.theme = Theme::DARK.with(active_border_color: Color::CYAN)
   #
-  # Tokens deliberately cover only the *accents* Tuile paints. Everything
-  # else inherits the terminal's own default foreground/background, which
-  # already matches the user's terminal theme perfectly — that's why there
-  # is no global `bg`/`fg` token.
-  #
-  # Every token is a {Color} — and must be passed as one. Unlike the
-  # lenient {Color.coerce} call sites elsewhere in the framework, a theme
-  # is declared once per app, so it takes only {Color} instances: at a
-  # declaration site `Color.palette(130)` documents itself in a way the
-  # bare `130` does not (palette index? RGB channel?) — and the named
-  # palette constants (`Color::DARK_ORANGE3` *is* 130; see
-  # {Color::PALETTE_NAMES}) go one step further.
-  #
   # ## App-specific tokens
   #
-  # Beyond the built-in tokens, an app can carry its own colors in
-  # {#custom} — a frozen `Hash{Symbol => Color}` member. Look them up with
-  # {#[]} (fail-fast: a typo raises `KeyError`) and render with the
-  # generic {#fg} / {#bg} helpers:
+  # An app carries its own colors in {#custom} (frozen `Hash{Symbol => Color}`).
+  # Look them up with {#[]} (fail-fast on typos) and render with the generic
+  # {#fg} / {#bg} helpers; subclass for semantic readers (`Data#with` keeps the
+  # subclass). Pair dark/light variants in a {ThemeDef} for {Screen#theme_def=}.
   #
   #   theme = Theme::DARK.with(custom: { accent: Color::DARK_ORANGE })
   #   theme[:accent]              # => Color, e.g. for StyledString#with_fg
   #   theme.fg(:accent, "NEW")    # => "\e[38;5;208mNEW\e[0m"
   #
-  # Apps wanting semantic readers can subclass — `Data#with` preserves the
-  # subclass, so an `AppTheme` stays an `AppTheme` through `with`:
-  #
   #   class AppTheme < Tuile::Theme
   #     def accent(text) = fg(:accent, text)
   #   end
   #
-  # Pair the dark and light variants in a {ThemeDef} and hand it to
-  # {Screen#theme_def=} so OS appearance flips pick the right one.
+  # 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
+  # own. Baked content colors ({Component::Label} text and friends) can't:
+  # they live in a frozen {StyledString} and still need the hook.
   #
   # @!attribute [r] active_bg_color
   #   Background highlight of the component the user is interacting with:
@@ -117,6 +102,58 @@ module Tuile
     #   loudly, not paint in a default.
     def [](token) = custom.fetch(token)
 
+    # The built-in chrome color tokens — every {Data} member bar {#custom}. A
+    # {Ref} resolves a name in this set as the chrome color; anything else as a
+    # {#custom} token.
+    # @return [Array<Symbol>]
+    CHROME_TOKENS = (members - %i[custom]).freeze
+
+    # @param name [Symbol] a token name.
+    # @return [Boolean] true iff `name` is a built-in chrome token (see
+    #   {CHROME_TOKENS}) rather than a {#custom} one.
+    def self.chrome_token?(name) = CHROME_TOKENS.include?(name)
+
+    # Builds a {Ref} — a live theme reference for a late-resolved color slot
+    # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
+    # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
+    #   a {#custom} token name.
+    # @return [Ref]
+    def self.ref(name) = Ref.new(name)
+
+    # 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:
+    #
+    #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
+    #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
+    #
+    # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
+    # one; a chrome name takes precedence on the (pathological) collision. This
+    # does *not* add a global bg/fg token — it only lets a slot point at a
+    # color the theme *already* carries, resolved the same way framework chrome
+    # already resolves it.
+    #
+    # Distinct from {Color.coerce}'s symbol support, which names one of the 16
+    # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
+    # re-reads it each paint.
+    #
+    # Immutable.
+    class Ref < Data.define(:name)
+      # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
+      # chrome reader when `name` is one ({Theme.chrome_token?}), else a
+      # {#custom} token.
+      # @param theme [Theme]
+      # @return [Color]
+      # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
+      #   token in `theme`.
+      def resolve(theme)
+        return theme.public_send(name) if Theme.chrome_token?(name)
+
+        theme[name]
+      end
+    end
+
     # Renders `text` in the foreground color of the app-specific `token`
     # — the generic counterpart of {#hint} for {#custom} tokens.
     # @param token [Symbol]

data/lib/tuile/version.rb

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

data/lib/tuile.rb

@@ -32,5 +32,9 @@ module Tuile
   end
 
   loader = Zeitwerk::Loader.for_gem
+  # Keeps Tuile's one optional dependency optional: the file requires
+  # `bigdecimal` at load, so a host app calling Zeitwerk::Loader.eager_load_all
+  # would otherwise raise LoadError for a component it never names.
+  loader.do_not_eager_load("#{__dir__}/tuile/component/big_decimal_field.rb")
   loader.setup
 end