tuile 0.4.0 → 0.6.0

data/lib/tuile/screen.rb

@@ -35,6 +35,9 @@ module Tuile
       @repainting = Set.new
       # Until the event loop is run, we pretend we're in the UI thread.
       @pretend_ui_lock = true
+      @scheme = detect_scheme
+      @theme_def = ThemeDef.default
+      @theme = @theme_def.for(@scheme)
       # Structural root of the component tree: holds tiled content, popup
       # stack and status bar.
       @pane = ScreenPane.new
@@ -93,6 +96,66 @@ module Tuile
     # @return [Size] current screen size.
     attr_reader :size
 
+    # The color {Theme} built-in components read at paint time: the member
+    # of {#theme_def} matching the terminal background detected at
+    # construction (see {TerminalBackground.detect}; inconclusive means
+    # dark). While the event loop runs, terminals supporting mode 2031
+    # push OS appearance changes ({EventQueue::ColorSchemeEvent}) and the
+    # screen re-picks from {#theme_def}.
+    # @return [Theme]
+    attr_reader :theme
+
+    # The app's {ThemeDef} — the dark/light {Theme} pair the screen picks
+    # {#theme} from, at startup and on every OS appearance flip. Starts as
+    # {ThemeDef.default} ({ThemeDef::DEFAULT} unless reassigned — tests
+    # do, see {ThemeDef.default=}). Assigning a custom definition is the
+    # durable way to theme an app: unlike a bare {#theme=}, it survives
+    # the user toggling the OS appearance.
+    # @return [ThemeDef]
+    attr_reader :theme_def
+
+    # Replaces the theme definition and immediately applies the member
+    # matching the current color scheme (via {#theme=}, so the whole UI
+    # restyles — or nothing repaints if that member equals the current
+    # theme).
+    # @param theme_def [ThemeDef]
+    # @return [void]
+    def theme_def=(theme_def)
+      raise TypeError, "expected ThemeDef, got #{theme_def.inspect}" unless theme_def.is_a?(ThemeDef)
+
+      check_locked
+      @theme_def = theme_def
+      self.theme = @theme_def.for(@scheme)
+    end
+
+    # Replaces the theme and restyles the whole UI: fires
+    # {Component#on_theme_changed} across the attached tree (so the app can
+    # rebuild styled content whose colors were derived from the old theme),
+    # refreshes the status bar and invalidates every attached component so
+    # the next repaint uses the new colors. No-op when `new_theme` equals
+    # the current theme.
+    #
+    # This is a transient override: the next OS appearance flip re-picks
+    # from {#theme_def} and replaces it. To theme an app durably, assign
+    # {#theme_def=} instead.
+    #
+    # Note status-bar hints supplied by the host as preformatted strings
+    # (see {#register_global_shortcut}) have their colors baked in and are
+    # not restyled by this.
+    # @param new_theme [Theme]
+    # @return [void]
+    def theme=(new_theme)
+      raise TypeError, "expected Theme, got #{new_theme.inspect}" unless new_theme.is_a?(Theme)
+
+      check_locked
+      return if @theme == new_theme
+
+      @theme = new_theme
+      @pane&.on_tree(&:on_theme_changed)
+      refresh_status_bar
+      needs_full_repaint
+    end
+
     # @return [Array<Component>] currently active popup components (forwarded
     #   to {ScreenPane}). The array must not be modified!
     def popups = @pane.popups
@@ -172,7 +235,7 @@ module Tuile
       top_popup = @pane.popups.last
       globals = global_shortcut_hints(popup_open: !top_popup.nil?)
       @pane.status_bar.text = if top_popup.nil?
-                                ["q #{Rainbow("quit").cadetblue}", *globals,
+                                ["q #{@theme.hint("quit")}", *globals,
                                  active_window&.keyboard_hint].compact.reject(&:empty?).join("  ")
                               else
                                 [*globals, top_popup.keyboard_hint].reject(&:empty?).join("  ")
@@ -224,10 +287,15 @@ module Tuile
       @pretend_ui_lock = false
       $stdin.echo = false
       print MouseEvent.start_tracking if capture_mouse
+      # Follow OS light/dark flips live: terminals supporting mode 2031
+      # push color-scheme reports that the key thread turns into
+      # {EventQueue::ColorSchemeEvent}s.
+      print TerminalBackground::NOTIFY_ON
       $stdin.raw do
         event_loop
       end
     ensure
+      print TerminalBackground::NOTIFY_OFF
       print MouseEvent.stop_tracking if capture_mouse
       print TTY::Cursor.show
       $stdin.echo = true
@@ -272,7 +340,7 @@ module Tuile
     #
     #   screen.register_global_shortcut(Keys::CTRL_L,
     #                                   over_popups: true,
-    #                                   hint: "^L #{Rainbow("log").cadetblue}") do
+    #                                   hint: "^L #{screen.theme.hint("log")}") do
     #     log_popup.open
     #   end
     #
@@ -283,8 +351,9 @@ module Tuile
     #   (default), the shortcut is suppressed while any popup is open and
     #   the popup gets the key instead.
     # @param hint [String, nil] preformatted status-bar hint (e.g.
-    #   `"^L #{Rainbow("log").cadetblue}"`). When nil (default) the shortcut
-    #   is silent in the status bar.
+    #   `"^L #{screen.theme.hint("log")}"`). When nil (default) the shortcut
+    #   is silent in the status bar. The colors are baked into the string,
+    #   so a later {#theme=} does not restyle it — re-register if needed.
     # @yield invoked with no arguments when `key` is pressed.
     # @return [void]
     def register_global_shortcut(key, over_popups: false, hint: nil, &block)
@@ -476,6 +545,27 @@ module Tuile
 
     private
 
+    # Startup color scheme: `:light` when {TerminalBackground.detect}
+    # reports a light terminal background, `:dark` otherwise (including
+    # when detection is inconclusive). Runs in the constructor — the
+    # OSC 11 reply arrives on stdin, which is only safe to read before
+    # {EventQueue#start_key_thread} owns it. {FakeScreen} overrides this
+    # to pin `:dark`, keeping specs deterministic and off the test
+    # runner's TTY.
+    # @return [Symbol] `:dark` or `:light`.
+    def detect_scheme
+      TerminalBackground.detect == :light ? :light : :dark
+    end
+
+    # An OS appearance flip arrived (mode-2031 report): remember the
+    # scheme and apply the matching member of {#theme_def}.
+    # @param scheme [Symbol] `:dark` or `:light`.
+    # @return [void]
+    def on_color_scheme(scheme)
+      @scheme = scheme
+      self.theme = @theme_def.for(@scheme)
+    end
+
     # Walks the current modal scope in pre-order, collects tab stops, and
     # advances focus by one (wrapping). When the focused component isn't in
     # the tab order (e.g. focus is parked on a popup/window chrome with no
@@ -596,8 +686,12 @@ module Tuile
         when EventQueue::TTYSizeEvent
           @size = event.size
           layout
+        when EventQueue::ColorSchemeEvent
+          on_color_scheme(event.scheme)
         when EventQueue::EmptyQueueEvent
           repaint
+        when Proc
+          event.call
         end
       rescue StandardError => e
         @on_error.call(e)

data/lib/tuile/sizing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A sizing policy for a slot whose position is managed by a parent
+  # component (e.g. {Component::Window#footer}). Resolves one dimension at a
+  # time via {#resolve}, so the same value works for widths and heights.
+  #
+  # Three policies exist:
+  #
+  # - {FILL} — take everything the slot offers;
+  # - {WRAP_CONTENT} — take the component's natural extent (its
+  #   {Component#content_size}), clamped to the slot;
+  # - {.fixed} — take exactly the given number of cells, clamped to the slot.
+  #
+  # Note that {WRAP_CONTENT} only makes sense for components that report a
+  # natural {Component#content_size} ({Component::Label}, {Component::Button},
+  # {Component::List}, …). Input components ({Component::TextField} et al.)
+  # report {Size::ZERO}, so a wrap-content slot collapses to zero width —
+  # i.e. the component becomes invisible. Use {.fixed} or {FILL} for those.
+  #
+  # @!attribute [r] mode
+  #   @return [Symbol] `:fill`, `:wrap_content` or `:fixed`.
+  # @!attribute [r] amount
+  #   @return [Integer, nil] the cell count for `:fixed`; `nil` otherwise.
+  class Sizing < Data.define(:mode, :amount)
+    # @param amount [Integer] the number of cells to occupy; 0 or greater.
+    # @return [Sizing] a fixed-size policy.
+    def self.fixed(amount)
+      raise TypeError, "expected Integer, got #{amount.inspect}" unless amount.is_a?(Integer)
+      raise ArgumentError, "amount must not be negative, got #{amount}" if amount.negative?
+
+      new(mode: :fixed, amount: amount)
+    end
+
+    # Resolves one dimension of a slot.
+    # @param available [Integer] cells the slot offers; 0 or greater.
+    # @param content [Integer] the component's natural extent on this axis
+    #   (one dimension of its {Component#content_size}).
+    # @return [Integer] the resolved extent, always in `0..available`.
+    def resolve(available, content)
+      case mode
+      when :fill then available
+      when :fixed then amount.clamp(0, available)
+      when :wrap_content then content.clamp(0, available)
+      else raise ArgumentError, "unknown mode #{mode.inspect}"
+      end
+    end
+
+    # Occupy everything the slot offers.
+    # @return [Sizing]
+    FILL = new(mode: :fill, amount: nil)
+
+    # Occupy the component's natural {Component#content_size}, clamped to the
+    # slot. Components reporting {Size::ZERO} collapse to invisibility — see
+    # the class doc.
+    # @return [Sizing]
+    WRAP_CONTENT = new(mode: :wrap_content, amount: nil)
+  end
+end

data/lib/tuile/styled_string.rb

@@ -53,18 +53,16 @@ module Tuile
     # Raised by {.parse} on malformed or unsupported escape sequences.
     class ParseError < Error; end
 
-    # A frozen value type describing the visual style of a {Span}.
-    #
-    # `fg` and `bg` accept:
-    # - `nil` — the terminal default (SGR 39 / 49)
-    # - a symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright ANSI colors
-    # - an Integer 0..255 — 256-color palette index (SGR 38;5;N / 48;5;N)
-    # - an `[r, g, b]` Array of three 0..255 Integers — 24-bit RGB
+    # A frozen value type describing the visual style of a {Span}. Colors are
+    # stored as {Color} instances (or `nil` for the terminal default); inputs
+    # to {.new} and {#merge} are coerced via {Color.coerce}, so the four
+    # accepted color forms — `nil`, Symbol, Integer 0..255, RGB Array — work
+    # transparently.
     #
     # @!attribute [r] fg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bold
     #   @return [Boolean]
     # @!attribute [r] italic
@@ -72,42 +70,16 @@ module Tuile
     # @!attribute [r] underline
     #   @return [Boolean]
     class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
-      # Symbolic color names recognized by {#fg} and {#bg}. Order is
-      # significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg
-      # / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 /
-      # 100..107).
-      # @return [Array<Symbol>]
-      COLOR_SYMBOLS = %i[
-        black red green yellow blue magenta cyan white
-        bright_black bright_red bright_green bright_yellow
-        bright_blue bright_magenta bright_cyan bright_white
-      ].freeze
-
-      # @param fg [Symbol, Integer, Array<Integer>, nil]
-      # @param bg [Symbol, Integer, Array<Integer>, nil]
+      # @param fg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
+      # @param bg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bold [Boolean]
       # @param italic [Boolean]
       # @param underline [Boolean]
       # @return [Style]
       # @raise [ArgumentError] when a color is not one of the accepted forms.
       def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
-        validate_color!(fg, :fg)
-        validate_color!(bg, :bg)
-        super(fg:, bg:, bold:, italic:, underline:)
-      end
-
-      # @param color [Object]
-      # @param which [Symbol]
-      # @return [void]
-      def self.validate_color!(color, which)
-        return if color.nil? || COLOR_SYMBOLS.include?(color)
-        return if color.is_a?(Integer) && color.between?(0, 255)
-        return if color.is_a?(Array) && color.length == 3 &&
-                  color.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }
-
-        raise ArgumentError, "invalid #{which} color: #{color.inspect}"
+        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:)
       end
-      private_class_method :validate_color!
 
       # The style with no color and no attributes — what the terminal shows
       # without any SGR applied.
@@ -149,11 +121,11 @@ module Tuile
     # supported SGR alphabet raises {ParseError}.
     class Parser
       # @return [Array<Symbol>]
-      STANDARD_COLORS = Style::COLOR_SYMBOLS[0, 8].freeze
+      STANDARD_COLORS = Color::COLOR_SYMBOLS[0, 8].freeze
       private_constant :STANDARD_COLORS
 
       # @return [Array<Symbol>]
-      BRIGHT_COLORS = Style::COLOR_SYMBOLS[8, 8].freeze
+      BRIGHT_COLORS = Color::COLOR_SYMBOLS[8, 8].freeze
       private_constant :BRIGHT_COLORS
 
       # @param input [String]
@@ -487,9 +459,9 @@ module Tuile
     # `underline`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     #
-    # @param bg [Symbol, Integer, Array<Integer>, nil] background color, in
-    #   any of the forms accepted by {Style.new}. `nil` clears bg back to
-    #   the terminal default.
+    # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background
+    #   color, coerced via {Color.coerce}. `nil` clears bg back to the
+    #   terminal default.
     # @return [StyledString]
     def with_bg(bg)
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bg: bg)) })
@@ -500,9 +472,9 @@ module Tuile
     # `underline`). The new fg overlays without dropping background colors or
     # text attributes the original styling carried.
     #
-    # @param fg [Symbol, Integer, Array<Integer>, nil] foreground color, in
-    #   any of the forms accepted by {Style.new}. `nil` clears fg back to
-    #   the terminal default.
+    # @param fg [Color, Symbol, Integer, Array<Integer>, nil] foreground
+    #   color, coerced via {Color.coerce}. `nil` clears fg back to the
+    #   terminal default.
     # @return [StyledString]
     def with_fg(fg)
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(fg: fg)) })
@@ -556,26 +528,21 @@ module Tuile
       codes << (to.bold ? 1 : 22) if from.bold != to.bold
       codes << (to.italic ? 3 : 23) if from.italic != to.italic
       codes << (to.underline ? 4 : 24) if from.underline != to.underline
-      codes.concat(color_codes(to.fg, base: 30, ext: 38)) if from.fg != to.fg
-      codes.concat(color_codes(to.bg, base: 40, ext: 48)) if from.bg != to.bg
+      codes.concat(color_codes(to.fg, target: :fg)) if from.fg != to.fg
+      codes.concat(color_codes(to.bg, target: :bg)) if from.bg != to.bg
       return "" if codes.empty?
 
       "\e[#{codes.join(";")}m"
     end
 
-    # @param color [Symbol, Integer, Array<Integer>, nil]
-    # @param base [Integer] base SGR code — 30 for fg, 40 for bg.
-    # @param ext [Integer] extended-color SGR code — 38 for fg, 48 for bg.
-    # @return [Array<Integer>]
-    def color_codes(color, base:, ext:)
-      case color
-      when nil then [base + 9]
-      when Symbol
-        idx = Style::COLOR_SYMBOLS.index(color)
-        idx < 8 ? [base + idx] : [base + 60 + (idx - 8)]
-      when Integer then [ext, 5, color]
-      when Array then [ext, 2, *color]
-      end
+    # @param color [Color, nil]
+    # @param target [Symbol] `:fg` or `:bg`.
+    # @return [Array<Integer>] SGR codes; `[39]` / `[49]` for the "default" reset
+    #   when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
+    def color_codes(color, target:)
+      return [target == :fg ? 39 : 49] if color.nil?
+
+      color.sgr_codes(target)
     end
 
     # @param start_or_range [Integer, Range]

data/lib/tuile/terminal_background.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Detects whether the terminal background is light or dark, so {Screen}
+  # can pick {Theme::LIGHT} or {Theme::DARK} automatically at startup.
+  #
+  # Two mechanisms, in order of reliability:
+  #
+  # 1. **OSC 11 query** — writes `ESC ] 11 ; ? BEL` to the terminal; modern
+  #    terminals (xterm, kitty, alacritty, wezterm, iTerm2, GNOME Terminal,
+  #    Windows Terminal) reply on stdin with the background color
+  #    (`\e]11;rgb:RRRR/GGGG/BBBB` + BEL or ST). The color's relative
+  #    luminance against a 0.5 threshold decides light vs dark. Terminals
+  #    that don't support the query simply never reply, so the read is
+  #    bounded by a short timeout.
+  # 2. **`COLORFGBG` env var** — rxvt/konsole export `"fg;bg"` ANSI palette
+  #    indices. Less reliable (stale across SSH/tmux, often unset); used
+  #    only when OSC 11 yields nothing.
+  #
+  # **Timing matters**: the OSC 11 reply arrives on stdin, so the query
+  # must complete before {EventQueue#start_key_thread} owns stdin —
+  # otherwise the reply bytes get consumed as garbage keystrokes. {Screen}
+  # calls {.detect} from its constructor, which apps run before
+  # {Screen#run_event_loop}; don't call this after the event loop started.
+  module TerminalBackground
+    # How long to wait for the OSC 11 reply. Generous for a local
+    # terminal; bounded so unsupporting terminals (which never reply)
+    # don't stall startup.
+    # @return [Float] seconds.
+    QUERY_TIMEOUT = 0.1
+
+    # The OSC 11 background-color query, BEL-terminated.
+    # @return [String]
+    QUERY = "\e]11;?\a"
+
+    # Matches the OSC 11 reply. Components are 1–4 hex digits each
+    # (terminals vary); `rgba:` (4 components) also matches — the alpha
+    # tail is ignored.
+    # @return [Regexp]
+    REPLY = %r{\e\]11;rgba?:(\h{1,4})/(\h{1,4})/(\h{1,4})}
+
+    # Enables mode 2031: the terminal pushes a color-scheme report
+    # (`\e[?997;1n` dark / `\e[?997;2n` light) whenever the OS appearance
+    # flips — see {EventQueue::ColorSchemeEvent}. Terminals without
+    # support ignore the sequence. Written by {Screen#run_event_loop}.
+    # @return [String]
+    NOTIFY_ON = "\e[?2031h"
+
+    # Disables mode 2031 again; written when the event loop exits.
+    # @return [String]
+    NOTIFY_OFF = "\e[?2031l"
+
+    class << self
+      # Detects the terminal background. Queries OSC 11 when both `input`
+      # and `output` are TTYs, falling back to `COLORFGBG`.
+      #
+      # @param input [IO] where the OSC 11 reply arrives (the TTY input).
+      # @param output [IO] where the query is written (the TTY output).
+      # @param env [Hash{String => String}] environment for the `COLORFGBG`
+      #   fallback; defaults to `ENV` (which duck-types the `[]` lookup).
+      # @param timeout [Numeric] max seconds to wait for the OSC 11 reply.
+      # @return [Symbol, nil] `:light`, `:dark`, or nil when undetectable.
+      def detect(input: $stdin, output: $stdout, env: ENV, timeout: QUERY_TIMEOUT)
+        osc = query_osc11(input, output, timeout) if input.tty? && output.tty?
+        osc || from_colorfgbg(env["COLORFGBG"])
+      end
+
+      private
+
+      # Writes the OSC 11 query and classifies the reply. The whole
+      # exchange runs with `input` in raw mode: the reply has no trailing
+      # newline, so a canonical-mode read would block past the timeout,
+      # and echo would smear the reply bytes onto the screen.
+      # @param input [IO]
+      # @param output [IO]
+      # @param timeout [Numeric]
+      # @return [Symbol, nil]
+      def query_osc11(input, output, timeout)
+        reply = input.raw do
+          output.write(QUERY)
+          output.flush
+          read_reply(input, timeout)
+        end
+        match = REPLY.match(reply)
+        match && classify(match.captures)
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      # Accumulates reply bytes until a BEL/ST terminator or the deadline.
+      # Terminals that don't support OSC 11 never reply — returning
+      # whatever arrived (usually nothing) lets the caller fail soft.
+      # @param input [IO]
+      # @param timeout [Numeric]
+      # @return [String]
+      def read_reply(input, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        buffer = +""
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return buffer if remaining <= 0 || IO.select([input], nil, nil, remaining).nil?
+
+          buffer << input.readpartial(256)
+          return buffer if buffer.include?("\a") || buffer.include?("\e\\")
+        end
+      rescue EOFError
+        buffer
+      end
+
+      # Relative luminance of the reported background, scaled per
+      # component hex width (xterm replies 4 digits per channel, others 2).
+      # @param components [Array<String>] three hex strings.
+      # @return [Symbol] `:light` or `:dark`.
+      def classify(components)
+        r, g, b = components.map { |c| c.to_i(16).fdiv((16**c.length) - 1) }
+        luminance = (0.2126 * r) + (0.7152 * g) + (0.0722 * b)
+        luminance > 0.5 ? :light : :dark
+      end
+
+      # `COLORFGBG` is `"fg;bg"` (rxvt sometimes `"fg;default;bg"`) with
+      # ANSI palette indices. White-ish backgrounds — 7 (white) and the
+      # bright range 9–15 — read as light; 0–6 and 8 as dark; anything
+      # else (missing, `"default"`, out of range) is inconclusive.
+      # @param value [String, nil]
+      # @return [Symbol, nil]
+      def from_colorfgbg(value)
+        bg = value&.split(";")&.last
+        return nil unless bg&.match?(/\A\d+\z/)
+
+        case bg.to_i
+        when 0..6, 8 then :dark
+        when 7, 9..15 then :light
+        end
+      end
+    end
+  end
+end