charming 0.2.0 → 0.2.2

data/lib/charming/internal/terminal/modified_key_parser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # ModifiedKeyParser decodes xterm CSI sequences that carry a modifier
+      # parameter — "\e[1;2A" (shift+up), "\e[3;5~" (ctrl+delete) — which
+      # tty-reader's key table does not cover. The modifier parameter encodes
+      # 1 + (1 shift | 2 alt | 4 ctrl | 8 meta); meta is treated as alt.
+      class ModifiedKeyParser
+        # "\e[1;<mod><final>" — arrows, home/end, and the SS3-style F1-F4 finals.
+        LETTER_PATTERN = /\A\e\[1;(\d+)([A-DFHPQRS])\z/
+
+        # "\e[<code>;<mod>~" — insert/delete, page keys, home/end, F5-F12.
+        TILDE_PATTERN = /\A\e\[(\d+);(\d+)~\z/
+
+        LETTER_KEYS = {
+          "A" => :up, "B" => :down, "C" => :right, "D" => :left,
+          "F" => :end, "H" => :home,
+          "P" => :f1, "Q" => :f2, "R" => :f3, "S" => :f4
+        }.freeze
+
+        TILDE_KEYS = {
+          1 => :home, 2 => :insert, 3 => :delete, 4 => :end,
+          5 => :page_up, 6 => :page_down, 7 => :home, 8 => :end,
+          15 => :f5, 17 => :f6, 18 => :f7, 19 => :f8,
+          20 => :f9, 21 => :f10, 23 => :f11, 24 => :f12
+        }.freeze
+
+        SHIFT_BIT = 1
+        ALT_BIT = 2
+        CTRL_BIT = 4
+        META_BIT = 8
+
+        # Parses *raw* into a KeyEvent with modifier flags, or nil when it is not
+        # a modified CSI sequence.
+        def self.parse(raw)
+          return nil unless raw.is_a?(String)
+
+          if (match = raw.match(LETTER_PATTERN))
+            build_event(LETTER_KEYS[match[2]], match[1].to_i)
+          elsif (match = raw.match(TILDE_PATTERN))
+            build_event(TILDE_KEYS[match[1].to_i], match[2].to_i)
+          end
+        end
+
+        def self.build_event(key, modifier_param)
+          return nil unless key
+
+          bits = modifier_param - 1
+          Events::KeyEvent.new(
+            key: key,
+            shift: bits.anybits?(SHIFT_BIT),
+            alt: bits.anybits?(ALT_BIT | META_BIT),
+            ctrl: bits.anybits?(CTRL_BIT)
+          )
+        end
+
+        private_class_method :build_event
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/mouse_parser.rb

@@ -5,21 +5,23 @@ module Charming
     module Terminal
       # MouseParser parses raw terminal escape sequences into MouseEvent objects.
       # Supports both modern SGR sequences (the most common, used by current terminals)
-      # and the older 3-byte legacy sequences. The public API is class methods; no
-      # instance state is required.
+      # and the older 3-byte legacy sequences. Both encodings pack modifiers and motion
+      # into the button code: bit 2 shift, bit 3 alt/meta, bit 4 ctrl, bit 5 motion.
+      # SGR signals release with a final "m" instead of "M". The public API is class
+      # methods; no instance state is required.
       class MouseParser
-        # Matches an SGR-encoded mouse sequence: "\e[<button;col;row[mode]M"
-        SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)([HmMhCc]?)(M|m)/
+        # Matches an SGR-encoded mouse sequence: "\e[<button;col;row" + "M" (press) or "m" (release).
+        SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)(M|m)/
 
         # Matches the legacy 3-byte mouse sequence: "\e[M" followed by 3 bytes.
         LEGACY_PATTERN = /\e\[M(.{3})/
 
-        # Maps raw button codes to semantic symbols used by MouseEvent#button_name.
-        BUTTON_MAP = {
-          0 => :left, 1 => :middle, 2 => :right, 3 => :release,
-          64 => :scroll_up, 65 => :scroll_down,
-          66 => :scroll_up, 67 => :scroll_down
-        }.freeze
+        # Button-code bits for modifier keys and motion (shared by SGR and legacy).
+        SHIFT_BIT = 4
+        ALT_BIT = 8
+        CTRL_BIT = 16
+        MOTION_BIT = 32
+        FLAG_BITS = SHIFT_BIT | ALT_BIT | CTRL_BIT | MOTION_BIT
 
         # Returns true when *raw* looks like a recognizable mouse sequence (SGR or legacy).
         # Lets the TTYBackend short-circuit and dispatch to MouseParser without allocation.
@@ -41,23 +43,13 @@ module Charming
           nil
         end
 
-        # Parses an SGR-format mouse sequence. Decodes button code, 1-based (col, row),
-        # the modifier "C" (ctrl) and "M" (shift) suffix, and the highlight alt (256-color)
-        # sequence as a heuristic for the alt modifier.
+        # Parses an SGR-format mouse sequence: button code with flag bits, 1-based
+        # (col, row), and the press/release final byte.
         def self.parse_sgr(raw)
           match = raw.match(SGR_PATTERN)
           return nil unless match
 
-          button_code = match[1].to_i
-          col = match[2].to_i - 1
-          row = match[3].to_i - 1
-          mode = match[4]
-
-          ctrl = mode == "C"
-          alt = raw.include?("\e[38;5;")
-          shift = mode == "M"
-
-          Events::MouseEvent.new(button: button_code, x: col, y: row, ctrl: ctrl, alt: alt, shift: shift)
+          build_event(match[1].to_i, match[2].to_i - 1, match[3].to_i - 1, release: match[4] == "m")
         end
 
         # Parses a legacy 3-byte mouse sequence. Each of the 3 bytes has 32 subtracted
@@ -69,12 +61,25 @@ module Charming
           bytes = match[1].bytes
           return nil unless bytes.length == 3
 
-          button_code = bytes[0] - 32
-          col = bytes[1] - 32
-          row = bytes[2] - 32
+          build_event(bytes[0] - 32, bytes[1] - 32, bytes[2] - 32, release: false)
+        end
 
-          Events::MouseEvent.new(button: button_code, x: col, y: row)
+        # Builds a MouseEvent from a raw button *code*, splitting out the modifier
+        # and motion flag bits so `button` carries only the button/wheel identity.
+        def self.build_event(code, x, y, release:)
+          Events::MouseEvent.new(
+            button: code & ~FLAG_BITS,
+            x: x,
+            y: y,
+            shift: code.anybits?(SHIFT_BIT),
+            alt: code.anybits?(ALT_BIT),
+            ctrl: code.anybits?(CTRL_BIT),
+            motion: code.anybits?(MOTION_BIT),
+            release: release
+          )
         end
+
+        private_class_method :build_event
       end
     end
   end

data/lib/charming/internal/terminal/tty_backend.rb

@@ -22,6 +22,19 @@ module Charming
         AUTO_WRAP_OFF = "\e[?7l"
         AUTO_WRAP_ON = "\e[?7h"
 
+        # Escape sequences for enabling/disabling bracketed-paste mode, and the markers
+        # the terminal wraps around pasted text.
+        BRACKETED_PASTE_ON = "\e[?2004h"
+        BRACKETED_PASTE_OFF = "\e[?2004l"
+        PASTE_START = "\e[200~"
+        PASTE_END = "\e[201~"
+
+        # Escape sequences for terminal focus reporting and the focus-in/out markers.
+        FOCUS_REPORTING_ON = "\e[?1004h"
+        FOCUS_REPORTING_OFF = "\e[?1004l"
+        FOCUS_IN = "\e[I"
+        FOCUS_OUT = "\e[O"
+
         # *input* and *output* default to `$stdin`/`$stdout` for normal terminal use;
         # tests can inject IO objects. *reader* is a TTY::Reader instance (created from
         # *input*/*output* when nil). *cursor* is the TTY::Cursor class used for cursor control.
@@ -37,13 +50,17 @@ module Charming
         end
 
         # Reads the next event. If a SIGWINCH was received, returns a ResizeEvent with the
-        # current terminal dimensions. Mouse escape sequences are parsed by MouseParser;
-        # other input is normalized via KeyNormalizer. Returns nil on timeout.
+        # current terminal dimensions. Bracketed pastes return a PasteEvent; mouse escape
+        # sequences are parsed by MouseParser; other input is normalized via KeyNormalizer.
+        # Returns nil on timeout.
         def read_event(timeout: nil)
           return resize_event if resized?
 
           raw = @reader.read_keypress(echo: false, raw: true, nonblock: timeout)
           return nil unless raw
+          return Events::FocusEvent.new(focused: true) if raw == FOCUS_IN
+          return Events::FocusEvent.new(focused: false) if raw == FOCUS_OUT
+          return paste_event(raw) if raw.start_with?(PASTE_START)
           return MouseParser.parse(raw) if MouseParser.sequence?(raw)
 
           @key_normalizer.normalize(raw)
@@ -51,6 +68,87 @@ module Charming
           nil
         end
 
+        # True when stdin has bytes ready to read right now — a genuine nonblocking check (0s
+        # wait), unlike read_event whose tty-reader nonblock path waits up to 0.1s. Lets the
+        # runtime drain buffered key auto-repeat and stop the instant the buffer empties.
+        def input_pending?
+          resized? || !@input.wait_readable(0).nil?
+        end
+
+        # Emits the ANSI sequence enabling terminal focus reporting. Idempotent.
+        def enable_focus_reporting
+          return if @focus_reporting
+
+          write_control(FOCUS_REPORTING_ON)
+          @focus_reporting = true
+        end
+
+        # Emits the ANSI sequence disabling terminal focus reporting. Idempotent.
+        def disable_focus_reporting
+          return unless @focus_reporting
+
+          write_control(FOCUS_REPORTING_OFF)
+          @focus_reporting = false
+        end
+
+        # Emits the ANSI sequence enabling bracketed-paste mode. Idempotent.
+        def enable_bracketed_paste
+          return if @bracketed_paste
+
+          write_control(BRACKETED_PASTE_ON)
+          @bracketed_paste = true
+        end
+
+        # Emits the ANSI sequence disabling bracketed-paste mode. Idempotent.
+        def disable_bracketed_paste
+          return unless @bracketed_paste
+
+          write_control(BRACKETED_PASTE_OFF)
+          @bracketed_paste = false
+        end
+
+        # Returns the terminal to its normal state for a shell suspend (Ctrl+Z):
+        # reporting modes off, cursor visible, primary screen, cooked input.
+        def suspend
+          @mouse_was_enabled = @mouse_enabled
+          disable_mouse_tracking
+          disable_bracketed_paste
+          disable_focus_reporting
+          show_cursor
+          leave_alt_screen
+          @input.cooked! if @input.respond_to?(:cooked!)
+        end
+
+        # Re-enters the TUI after a resume (SIGCONT): raw/no-echo input, alt
+        # screen, hidden cursor, and the reporting modes that were active before
+        # the suspend. The caller is responsible for triggering a repaint.
+        def resume
+          @input.raw! if @input.respond_to?(:raw!)
+          @input.echo = false if @input.respond_to?(:echo=)
+          enter_alt_screen
+          hide_cursor
+          enable_mouse_tracking(motion: @mouse_motion || :drag) if @mouse_was_enabled
+          enable_bracketed_paste
+          enable_focus_reporting
+          clear
+        end
+
+        # The OSC 11 background-color query and the terminators a reply may end with.
+        BACKGROUND_QUERY = "\e]11;?\e\\"
+        OSC_TERMINATORS = ["\a", "\e\\"].freeze
+
+        # Queries the terminal's background color via OSC 11 and classifies the
+        # reply as :dark or :light. Returns nil when the input cannot be polled,
+        # the terminal stays silent past *timeout*, or the reply is unparseable.
+        # Call before the event loop starts — a reply arriving later would be
+        # read as keyboard input.
+        def query_background_color(timeout: 0.15)
+          return nil unless @input.respond_to?(:wait_readable)
+
+          write_control(BACKGROUND_QUERY)
+          UI::Background.parse_osc11(read_reply(timeout))
+        end
+
         # Keeps terminal input in raw/no-echo mode for the duration of a TUI run. Reading a
         # single keypress in raw mode is not enough: keys pressed while rendering or dispatching
         # events can otherwise be echoed into the alternate screen before the next read.
@@ -93,13 +191,15 @@ module Charming
 
         # Emits the ANSI sequences that enable terminal mouse reporting (press, motion, SGR).
         # Idempotent: skipped when mouse tracking is already enabled.
-        def enable_mouse_tracking
+        def enable_mouse_tracking(motion: :drag)
           return if @mouse_enabled
 
           write_control("\e[?1000h")
           write_control("\e[?1002h")
+          write_control("\e[?1003h") if motion == :all
           write_control("\e[?1006h")
           @mouse_enabled = true
+          @mouse_motion = motion
         end
 
         # Emits the ANSI sequences that disable terminal mouse reporting. Idempotent.
@@ -108,7 +208,7 @@ module Charming
 
           write_control("\e[?1000l")
           write_control("\e[?1002l")
-          write_control("\e[?1003l")
+          write_control("\e[?1003l") if @mouse_motion == :all
           write_control("\e[?1006l")
           @mouse_enabled = false
         end
@@ -138,6 +238,12 @@ module Charming
           end
         end
 
+        # Writes an out-of-band escape *sequence* (image transmission, clipboard, notification, title)
+        # raw — no cursor positioning, line-clearing, or auto-wrap handling that would corrupt it.
+        def write_escape(sequence)
+          write_control(sequence.payload)
+        end
+
         # Enters the alternate screen buffer.
         def enter_alt_screen
           write_control(ALT_SCREEN_ON)
@@ -173,6 +279,26 @@ module Charming
 
         private
 
+        # Accumulates an OSC reply from the input until a terminator arrives or
+        # *timeout* elapses. Returns whatever was read (possibly "").
+        def read_reply(timeout)
+          reply = +""
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          while (remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)) > 0
+            break unless @input.wait_readable(remaining)
+            break if append_reply_chunk(reply).nil?
+            break if OSC_TERMINATORS.any? { |terminator| reply.include?(terminator) }
+          end
+          reply
+        end
+
+        # Reads one available chunk into *reply*; nil at EOF or read error.
+        def append_reply_chunk(reply)
+          reply << @input.readpartial(64)
+        rescue IOError, SystemCallError
+          nil
+        end
+
         # True when the SIGWINCH flag has been set since the last read_event.
         def resized?
           @resized
@@ -185,6 +311,19 @@ module Charming
           Events::ResizeEvent.new(width: width, height: height)
         end
 
+        # Builds a PasteEvent from a bracketed-paste chunk, reading further keypresses
+        # until the paste-end marker arrives (large pastes can span multiple reads).
+        def paste_event(raw)
+          buffer = raw.delete_prefix(PASTE_START)
+          until buffer.include?(PASTE_END)
+            chunk = @reader.read_keypress(echo: false, raw: true, nonblock: 0.2)
+            break unless chunk
+
+            buffer << chunk
+          end
+          Events::PasteEvent.new(text: buffer.sub(/#{Regexp.escape(PASTE_END)}.*\z/mo, ""))
+        end
+
         # Writes a raw escape *sequence* to the output stream and flushes.
         def write_control(sequence)
           @output.write(sequence)

data/lib/charming/presentation/component.rb

@@ -4,5 +4,12 @@ module Charming
   # Component is the base class for all reusable terminal widgets. It inherits from View to gain assigns,
   # helper methods (text, box, row, column, etc.), and rendering via render.
   class Component < View
+    # True for components that accept free-typed text (TextInput, TextArea, Form, …).
+    # While such a component is focused, the controller routes printable characters to
+    # it BEFORE global/content key bindings — so typing "q" or "?" into a field inserts
+    # the character instead of triggering an app shortcut.
+    def captures_text?
+      false
+    end
   end
 end

data/lib/charming/presentation/components/activity_indicator.rb

@@ -154,7 +154,7 @@ module Charming
       end
 
       def widest_ellipsis_width
-        @widest_ellipsis_width ||= ELLIPSIS_FRAMES.map { |frame| UI::Width.measure(frame) }.max
+        @widest_ellipsis_width ||= UI::Width.widest(ELLIPSIS_FRAMES)
       end
 
       # Interpolates between gradient[0] and gradient[1] at the fractional +position+ (0.0 to 1.0).
@@ -162,24 +162,7 @@ module Charming
       def color_at(position)
         return gradient.first unless indicator_width > 1
 
-        blend(gradient.first, gradient.last, position / (indicator_width - 1).to_f)
-      end
-
-      # Blends two hex colors by interpolating their red/green/blue components at fractional +amount+.
-      # Accepts strings like "#ff0000" and produces a new "#rrggbb" string.
-      def blend(start_hex, end_hex, amount)
-        start_rgb = rgb(start_hex)
-        end_rgb = rgb(end_hex)
-        mixed = start_rgb.zip(end_rgb).map { |from, to| (from + ((to - from) * amount)).round }
-        "#%02x%02x%02x" % mixed
-      end
-
-      # Decomposes a hex color string ("#rrggbb") into an array of three integers [r, g, b].
-      def rgb(hex)
-        value = hex.to_s.delete_prefix("#")
-        raise ArgumentError, "gradient colors must be #rrggbb" unless value.match?(/\A[0-9a-fA-F]{6}\z/)
-
-        [value[0..1], value[2..3], value[4..5]].map { |part| part.to_i(16) }
+        UI::Gradient.blend(gradient.first, gradient.last, position / (indicator_width - 1).to_f)
       end
 
       # Advances the animation frame counter, wrapping around after +FRAME_COUNT+ (10) steps.

data/lib/charming/presentation/components/audio.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Audio is a one-line playback-status indicator for a {Charming::Audio::Player}. It
+    # reads the player's `playing?` state and renders a play/stop glyph with an optional
+    # *label*; pair it with a controller timer (or `on_task` re-render) to keep it live.
+    #
+    # Note: this view component (`Charming::Components::Audio`) is distinct from the
+    # playback engine namespace (`Charming::Audio`) — the component only displays state,
+    # the engine spawns the sound.
+    class Audio < Component
+      # *player* is the {Charming::Audio::Player} whose state is shown. *label* is an
+      # optional suffix (e.g. the track name) appended after the glyph. *theme* is the
+      # active theme, forwarded to the view layer.
+      def initialize(player:, label: nil, theme: nil)
+        super(theme: theme)
+        @player = player
+        @label = label
+      end
+
+      # Renders `▶`/`■` for playing/stopped, followed by the label when present.
+      def render
+        glyph = @player.playing? ? "▶" : "■"
+        return glyph unless @label
+
+        "#{glyph} #{@label}"
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/autocomplete.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Autocomplete is a combobox: a TextInput with a suggestion list beneath it,
+    # filtered live against the typed value. Up/down move through suggestions,
+    # Enter submits the highlighted suggestion (or the free text when nothing
+    # matches), Escape cancels.
+    #
+    #   Autocomplete.new(suggestions: ["ruby", "rails", "rspec"], value: "r")
+    #
+    # `handle_key` returns `[:submitted, value]` on Enter, `:cancelled` on Escape,
+    # `:handled` for consumed keys, nil otherwise.
+    class Autocomplete < Component
+      DEFAULT_MAX_SUGGESTIONS = 6
+
+      # The current typed value and the highlighted suggestion index.
+      attr_reader :selected_index
+
+      # *suggestions* is the full candidate list. *value*/*cursor* seed the inner
+      # TextInput. *max_suggestions* caps the visible dropdown rows.
+      def initialize(suggestions:, value: "", cursor: nil, placeholder: "", selected_index: 0,
+        max_suggestions: DEFAULT_MAX_SUGGESTIONS, theme: nil)
+        super(theme: theme)
+        @suggestions = Array(suggestions).map(&:to_s)
+        @input = TextInput.new(value: value, cursor: cursor, placeholder: placeholder)
+        @selected_index = selected_index
+        @max_suggestions = max_suggestions
+        clamp_selection
+      end
+
+      # The typed text.
+      def value
+        @input.value
+      end
+
+      # The inner input's cursor offset.
+      def cursor
+        @input.cursor
+      end
+
+      # The suggestions matching the current value (case-insensitive substring),
+      # capped at max_suggestions. All suggestions when the value is empty.
+      def filtered_suggestions
+        query = value.downcase
+        matches = query.empty? ? @suggestions : @suggestions.select { |s| s.downcase.include?(query) }
+        matches.first(@max_suggestions)
+      end
+
+      # Free-typed characters belong to this component while it is focused.
+      def captures_text?
+        true
+      end
+
+      # Enter submits, Escape cancels, up/down move the highlight, everything else
+      # edits the text (resetting the highlight).
+      def handle_key(event)
+        case Charming.key_of(event)
+        when :escape then :cancelled
+        when :enter then [:submitted, submission_value]
+        when :up then move_selection(-1)
+        when :down then move_selection(+1)
+        else
+          result = @input.handle_key(event)
+          clamp_selection if result
+          result
+        end
+      end
+
+      # Renders the input row followed by the suggestion dropdown.
+      def render
+        [input_line, *suggestion_lines].join("\n")
+      end
+
+      private
+
+      # The highlighted suggestion, or the raw text when none match.
+      def submission_value
+        filtered_suggestions[selected_index] || value
+      end
+
+      def input_line
+        @input.render
+      end
+
+      # One row per suggestion; the highlighted row in the selected style.
+      def suggestion_lines
+        filtered_suggestions.each_with_index.map do |suggestion, index|
+          line = "  #{suggestion}"
+          (index == selected_index) ? theme.selected.render(line) : theme.muted.render(line)
+        end
+      end
+
+      def move_selection(delta)
+        count = filtered_suggestions.length
+        return :handled if count.zero?
+
+        @selected_index = (selected_index + delta).clamp(0, count - 1)
+        :handled
+      end
+
+      def clamp_selection
+        max = [filtered_suggestions.length - 1, 0].max
+        @selected_index = selected_index.clamp(0, max)
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/badge.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Badge is a small inline label rendered as a styled pill — useful for versions,
+    # counts, and statuses inside status bars, lists, and headers.
+    #
+    #   Badge.new("v1.2").render            # themed default
+    #   Badge.new("3 errors", style: theme.warn).render
+    class Badge < Component
+      # *label* is the badge text. *style* overrides the default themed style.
+      def initialize(label, style: nil, theme: nil)
+        super(theme: theme)
+        @label = label.to_s
+        @badge_style = style
+      end
+
+      # Renders the pill: a space-padded label with the badge style applied.
+      def render
+        resolved_style.render(" #{@label} ")
+      end
+
+      private
+
+      # The user style or the theme's selected style (which guarantees contrast).
+      def resolved_style
+        @badge_style || theme.selected
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/breadcrumbs.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Breadcrumbs renders a navigation trail like `Home › Projects › My App`, with the
+    # final (current) item highlighted and ancestors muted.
+    class Breadcrumbs < Component
+      DEFAULT_SEPARATOR = " › "
+
+      # *items* is the trail (strings or anything responding to to_s), first-to-last.
+      # *separator* joins the items.
+      def initialize(items:, separator: DEFAULT_SEPARATOR, theme: nil)
+        super(theme: theme)
+        @items = Array(items).map(&:to_s)
+        @separator = separator
+      end
+
+      # Renders the trail; ancestors muted, current item in the title style.
+      def render
+        return "" if @items.empty?
+
+        *ancestors, current = @items
+        parts = ancestors.map { |item| theme.muted.render(item) }
+        parts << theme.title.render(current)
+        parts.join(theme.muted.render(@separator))
+      end
+    end
+  end
+end