charming 0.1.0 → 0.1.2

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

@@ -7,63 +7,78 @@ require "tty-screen"
 module Charming
   module Internal
     module Terminal
+      # TTYBackend is the production terminal backend. It reads key and mouse events from
+      # a TTY::Reader, normalizes them via KeyNormalizer and MouseParser, and writes output
+      # frames using TTY::Cursor and TTY::Screen. It also installs SIGWINCH and SIGINFO
+      # handlers so the runtime can react to terminal resize and focus changes.
       class TTYBackend
         include Adapter
 
+        # Escape sequences for entering/leaving the alternate screen buffer.
         ALT_SCREEN_ON = "\e[?1049h"
         ALT_SCREEN_OFF = "\e[?1049l"
-        CTRL_KEY_PATTERN = /\Actrl_(?<key>.+)\z/
-        MOUSE_SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)([HmMhCc]?)(M|m)/
-        MOUSE_LEGACY_PATTERN = /\e\[M(.{3})/
-        MOUSE_BUTTON_MAP = {
-          0 => :left, 1 => :middle, 2 => :right, 3 => :release,
-          64 => :scroll_up, 65 => :scroll_down,
-          66 => :scroll_up, 67 => :scroll_down
-        }.freeze
 
+        # Escape sequences for disabling/enabling automatic line wrapping during frame writes.
+        AUTO_WRAP_OFF = "\e[?7l"
+        AUTO_WRAP_ON = "\e[?7h"
+
+        # *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.
         def initialize(input: $stdin, output: $stdout, reader: nil, cursor: TTY::Cursor)
           @input = input
           @output = output
           @reader = reader || TTY::Reader.new(input: input, output: output)
           @cursor = cursor
+          @key_normalizer = KeyNormalizer.new(@reader)
           @resized = false
           @previous_winch_handler = nil
           @mouse_enabled = false
         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.
         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 MouseParser.parse(raw) if MouseParser.sequence?(raw)
 
-          return mouse_event(raw) if mouse_sequence?(raw)
-
-          normalize_keypress(raw)
+          @key_normalizer.normalize(raw)
         rescue Errno::EAGAIN, IO::WaitReadable
           nil
         end
 
+        # Installs a SIGWINCH handler that sets the internal `@resized` flag, returning
+        # the previous handler so it can be restored on teardown.
         def install_resize_handler
           @previous_winch_handler = Signal.trap("WINCH") { @resized = true }
         end
 
+        # Installs a SIGINFO handler that marks the terminal as having received focus.
+        # SIGINFO is sent by some terminals (notably macOS Terminal.app) on focus changes.
         def install_focus_handler
           # Terminal focus change: some terminals send a special sequence
           # when focus changes. We use this to throttle rendering.
           @previous_focus_handler = Signal.trap("INFO") { @focused = true }
         end
 
+        # Restores the previous SIGINFO handler.
         def restore_focus_handler
           Signal.trap("INFO", @previous_focus_handler) if @previous_focus_handler
           @previous_focus_handler = nil
         end
 
+        # Restores the previous SIGWINCH handler captured by `install_resize_handler`.
         def restore_resize_handler
           Signal.trap("WINCH", @previous_winch_handler) if @previous_winch_handler
           @previous_winch_handler = nil
         end
 
+        # Emits the ANSI sequences that enable terminal mouse reporting (press, motion, SGR).
+        # Idempotent: skipped when mouse tracking is already enabled.
         def enable_mouse_tracking
           return if @mouse_enabled
 
@@ -73,6 +88,7 @@ module Charming
           @mouse_enabled = true
         end
 
+        # Emits the ANSI sequences that disable terminal mouse reporting. Idempotent.
         def disable_mouse_tracking
           return unless @mouse_enabled
 
@@ -83,165 +99,96 @@ module Charming
           @mouse_enabled = false
         end
 
+        # Returns whether mouse tracking is currently enabled on this backend.
         def mouse_enabled?
           @mouse_enabled
         end
 
+        # Manually flags the backend as resized (used by tests or external integrations).
         def notify_resize
           @resized = true
         end
 
+        # Writes a full multi-line *frame* to the terminal, disabling auto-wrap during
+        # the write so overlong lines don't disturb the screen layout.
         def write_frame(frame)
-          @output.write(frame)
-          @output.flush
+          without_auto_wrap do
+            write_positioned_lines(frame.to_s.lines(chomp: true))
+          end
         end
 
+        # Writes a partial frame composed of [row, line] tuples (1-based rows).
         def write_lines(line_changes, **)
-          write_control(line_changes.map { |row, line| "\e[#{row};1H\e[2K#{line}" }.join)
+          without_auto_wrap do
+            write_control(line_changes.map { |row, line| "\e[#{row};1H\e[2K#{line}" }.join)
+          end
         end
 
+        # Enters the alternate screen buffer.
         def enter_alt_screen
           write_control(ALT_SCREEN_ON)
         end
 
+        # Leaves the alternate screen buffer.
         def leave_alt_screen
           write_control(ALT_SCREEN_OFF)
         end
 
+        # Shows the terminal cursor.
         def show_cursor
           write_control(@cursor.show)
         end
 
+        # Hides the terminal cursor.
         def hide_cursor
           write_control(@cursor.hide)
         end
 
+        # Clears the terminal screen and moves the cursor to (1, 1).
         def clear
           write_control(@cursor.clear_screen)
         end
 
+        # Moves the terminal cursor to the given 1-based (row, column).
         def move_cursor(row, column)
           write_control(@cursor.move_to(column - 1, row - 1))
         end
 
+        # Returns the current terminal dimensions as [width, height] via TTY::Screen.
         def size = [TTY::Screen.width, TTY::Screen.height]
 
         private
 
-        def mouse_sequence?(raw)
-          return false unless raw.is_a?(String)
-          return true if raw.match?(MOUSE_SGR_PATTERN)
-          return true if raw.start_with?("\e[M")
-
-          false
-        end
-
-        def mouse_event(raw)
-          if raw.match?(MOUSE_SGR_PATTERN)
-            parse_sgr_mouse(raw)
-          else
-            parse_legacy_mouse(raw)
-          end
-        end
-
-        def parse_sgr_mouse(raw)
-          match = raw.match(MOUSE_SGR_PATTERN)
-          return nil unless match
-
-          # \e[<button>;<col>;<row><mode>M
-          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"
-
-          MouseEvent.new(button: button_code, x: col, y: row, ctrl: ctrl, alt: alt, shift: shift)
-        end
-
-        def parse_legacy_mouse(raw)
-          # Legacy format: \e[M + 3 bytes (button, col, row)
-          # Each byte is 32 + value (space offset)
-          match = raw.match(MOUSE_LEGACY_PATTERN)
-          return nil unless match
-
-          bytes = match[1].bytes
-          return nil unless bytes.length == 3
-
-          button_code = bytes[0] - 32
-          col = bytes[1] - 32
-          row = bytes[2] - 32
-
-          MouseEvent.new(button: button_code, x: col, y: row)
-        end
-
+        # True when the SIGWINCH flag has been set since the last read_event.
         def resized?
           @resized
         end
 
+        # Consumes the resize flag, measures the current terminal, and returns a ResizeEvent.
         def resize_event
           @resized = false
           width, height = size
-          ResizeEvent.new(width: width, height: height)
+          Events::ResizeEvent.new(width: width, height: height)
         end
 
-        def normalize_keypress(keypress)
-          return nil unless keypress
-
-          key_name = @reader.console.keys[keypress]
-          return character_event(keypress) unless key_name
-
-          named_event(key_name)
-        end
-
-        def character_event(keypress)
-          KeyEvent.new(key: keypress.to_sym, char: keypress)
-        end
-
-        def named_event(key_name)
-          normalized = normalize_key_name(key_name)
-          KeyEvent.new(
-            key: normalized.fetch(:key),
-            char: normalized.fetch(:char, nil),
-            ctrl: normalized.fetch(:ctrl, false),
-            alt: normalized.fetch(:alt, false),
-            shift: normalized.fetch(:shift, false)
-          )
-        end
-
-        def normalize_key_name(key_name)
-          name = key_name.to_s
-          return ctrl_key(name) if name.match?(CTRL_KEY_PATTERN)
-          return {key: :tab, shift: true} if name == "back_tab"
-
-          {key: normalized_key(name), char: printable_char(name)}
-        end
-
-        def normalized_key(name)
-          return :enter if name == "return"
-
-          name.to_sym
-        end
-
-        def ctrl_key(name)
-          match = name.match(CTRL_KEY_PATTERN)
-          {key: match[:key].to_sym, ctrl: true}
+        # Writes a raw escape *sequence* to the output stream and flushes.
+        def write_control(sequence)
+          @output.write(sequence)
+          @output.flush
         end
 
-        def printable_char(name)
-          case name
-          when "space" then " "
-          when "enter", "return" then "\n"
-          when "tab" then "\t"
-          else
-            name if name.length == 1 && !name.match?(/[[:cntrl:]]/)
-          end
+        # Writes *lines* one row at a time, with each line preceded by an ANSI cursor
+        # position and a clear-to-end-of-line sequence.
+        def write_positioned_lines(lines)
+          write_control(lines.each_with_index.map { |line, index| "\e[#{index + 1};1H\e[2K#{line}" }.join)
         end
 
-        def write_control(sequence)
-          @output.write(sequence)
+        # Disables auto-wrap, yields, then re-enables it and flushes the output.
+        def without_auto_wrap
+          @output.write(AUTO_WRAP_OFF)
+          yield
+        ensure
+          @output.write(AUTO_WRAP_ON)
           @output.flush
         end
       end

data/lib/charming/presentation/component.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    # 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
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # ActivityIndicator renders a color-gradient progress or loading indicator
+      # as styled text. It produces a fixed-width row of characters whose colors
+      # interpolate between two gradient endpoints (or cycle through a single
+      # color). A label can be appended after the bar and an ellipsis that cycles
+      # through frames, useful for "loading" state display. Call `tick` to advance
+      # the frame counter, and call `render` to produce the styled output string.
+      class ActivityIndicator < Component
+        # Default character pool used for generating each position's character via stable hashing.
+        DEFAULT_CHARS = "0123456789abcdefABCDEF~!@#$%^&*+=_".chars.freeze
+
+        # The default two-color gradient applied across the bar width (red to cyan).
+        # The cyan endpoint mirrors the Phosphor theme palette's "cyan" token so the bar
+        # remains legible on Phosphor's dark navy background; gradient: accepts raw hex,
+        # so callers using a different theme should pass their own endpoints.
+        DEFAULT_GRADIENT = ["#ff0000", "#6FD0E3"].freeze
+
+        # The default label color for ellipsis and text portions when no custom
+        # label_style is provided.
+        DEFAULT_LABEL_COLOR = "#cccccc"
+
+        # Ellipsis frame sequence: four states cycle through "., "..", "...", and "" (empty).
+        ELLIPSIS_FRAMES = [".", "..", "...", ""].freeze
+
+        # Number of frames in the animation cycle before the indicator pattern repeats.
+        FRAME_COUNT = 10
+
+        # FNV-1a variant constants used by stable_hash for reproducible character selection per position.
+        FNV_OFFSET = 2_166_136_261
+        FNV_PRIME = 16_777_619
+        FNV_MASK = 0xffffffff
+
+        attr_reader :width, :label, :index, :seed, :chars, :gradient, :label_style
+
+        # Initializes a new ActivityIndicator with configurable visual parameters.
+        # width       — Display width of the gradient bar in characters (minimum 1). Default: 10.
+        # label       — Optional text label shown adjacent to the indicator.
+        # index       — Initial frame index for the ellipsis/frame animations. Default: 0.
+        # seed        — Hash seed that determines which characters appear at each position.
+        # chars       — Character pool to draw from (default is DEFAULT_CHARS).
+        # gradient    — Two-element array of hex color strings ["#rrggbb", "#rrggbb"] for interpolation.
+        # label_style — A Style object to use for rendering the label text; falls back to a gray foreground.
+        def initialize(width: 10, label: nil, index: 0, seed: 0, chars: DEFAULT_CHARS,
+          gradient: DEFAULT_GRADIENT, label_style: nil)
+          super()
+          raise ArgumentError, "chars cannot be empty" if chars.empty?
+
+          @width = [width.to_i, 1].max
+          @label = label
+          @index = index.to_i
+          @seed = seed
+          @chars = chars.map(&:to_s)
+          @gradient = gradient
+          @label_style = label_style
+        end
+
+        # Advances the frame counter forward by +count+ steps, allowing the displayed pattern to change.
+        # Accepts an integer count (converted via +to_i+). Returns self for chaining.
+        def tick(count = 1)
+          @index += count.to_i
+          self
+        end
+
+        # Renders the activity indicator as a styled string. If a label was provided,
+        # produces "bar ellipsis" alongside it; otherwise produces only the gradient bar.
+        # Returns a formatted string suitable for terminal rendering.
+        def render
+          return indicator unless label
+
+          "#{indicator} #{styled_label}#{styled_ellipsis}"
+        end
+
+        private
+
+        # Renders the full gradient bar as an array of styled characters joined into a single string.
+        # Each character at +position+ is selected by hashing together seed, frame, and position —
+        # making the pattern stable across renders — then styled with the interpolated gradient color
+        # at that position.
+        def indicator
+          Array.new(width) { |position| styled_char(position) }.join
+        end
+
+        # Selects a character for the bar at the given +position+, styles it with the gradient color
+        # interpolated for that position, and returns the result as a formatted string via +render+.
+        def styled_char(position)
+          style.foreground(color_at(position)).render(char_at(position))
+        end
+
+        # Chooses a character from self.chars by hashing seed:frame:position together with a stable
+        # FNV-1a hash. The resulting index is modulated against the character pool length, ensuring
+        # reproducible output across renders.
+        def char_at(position)
+          chars.fetch(stable_hash("#{seed}:#{frame}:#{position}") % chars.length)
+        end
+
+        # Renders the label text in its own style (or fallback gray color) via a Style renderer call.
+        def styled_label
+          label_style_or_default.render(label.to_s)
+        end
+
+        # Renders an ellipsis frame (".", "..", "...", or empty) based on (index / 4) mod 4, styled with the label style.
+        def styled_ellipsis
+          label_style_or_default.render(ellipsis_frame)
+        end
+
+        # Returns the current ellipsis frame string: one of ".", "..", "...", "". Cycles through four frames per tick.
+        def ellipsis_frame
+          ELLIPSIS_FRAMES.fetch((index / 4) % ELLIPSIS_FRAMES.length)
+        end
+
+        # Returns the label style if set, otherwise produces a gray foreground style for fallback rendering.
+        def label_style_or_default
+          label_style || style.foreground(DEFAULT_LABEL_COLOR)
+        end
+
+        # Interpolates between gradient[0] and gradient[1] at the fractional +position+ (0.0 to 1.0).
+        # Returns the first gradient color if width is 1; otherwise returns a blended hex string based on position.
+        def color_at(position)
+          return gradient.first unless width > 1
+
+          blend(gradient.first, gradient.last, position / (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) }
+        end
+
+        # Advances the animation frame counter, wrapping around after +FRAME_COUNT+ (10) steps.
+        def frame
+          index % FRAME_COUNT
+        end
+
+        # Produces a deterministic integer hash from the input string using FNV-1a hashing, ensuring the same
+        # characters appear at the same positions across multiple renderings of this indicator.
+        def stable_hash(value)
+          value.bytes.reduce(FNV_OFFSET) do |hash, byte|
+            ((hash ^ byte) * FNV_PRIME) & FNV_MASK
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # CommandPalette renders a fuzzy-searchable command picker UI. It wraps a TextInput for search
+      # input and a List for result display, dispatching key events between them. Users type to filter
+      # the registered commands by label match, navigate with up/down/home/end keys (delegated to List),
+      # confirm a selection with Enter (returns [:selected, command]), or cancel with Escape (returns :cancelled).
+      # State is serializable as a hash of value/cursor/selected_index for session persistence.
+      class CommandPalette < Component
+        Command = Data.define(:label, :value)
+
+        # A single command palette entry: a human-readable +label+ and a callable or
+        # method symbol +value+ that gets executed when the user selects it.
+        attr_reader :commands, :input
+
+        # Initializes the dropdown widget with a list of Command entries and search
+        # parameters for building the underlying TextInput (placeholder text, cursor
+        # position, value) and List (display height, initial selection). Returns void;
+        # the state is later serializable via +state+ for session persistence.
+        def initialize(commands:, placeholder: "Search commands", height: nil, value: "", cursor: nil, selected_index: 0, theme: nil)
+          super(theme: theme)
+          @commands = commands
+          @height = height
+          @input = TextInput.new(value: value, placeholder: placeholder, cursor: cursor)
+          @list = build_list(selected_index: selected_index)
+        end
+
+        # Returns the currently displayed Command entry in the List at the time of calling.
+        # Returns nil if no entry is highlighted (i.e., user has opened the palette but not
+        # moved the selection). Useful for retrieving the result after key handling.
+        def selected_command
+          list.selected_item
+        end
+
+        # Collects the current state of the TextInput and List into a serializable hash
+        # suitable for round-trip storage in session. Returns {value:, cursor:, selected_index:}.
+        def state
+          {
+            value: input.value,
+            cursor: input.cursor,
+            selected_index: list.selected_index
+          }
+        end
+
+        # Handles key events by routing them to the appropriate sub-component: Escape kills the
+        # palette returning :cancelled; up/down/home/end keys go to the List selection handler
+        # via handle_list_key; all other keys (including typed characters) are passed to the TextInput
+        # which manages cursor position and input filtering. If a list key match fails, falls through
+        # to the TextInput handler. Returns nil/nil if no handler consumed the event, or :cancelled when
+        # Escape is pressed.
+        def handle_key(event)
+          key = Charming.key_of(event)
+          return :cancelled if key == :escape
+
+          return handle_list_key(event) if list_key?(key)
+
+          handle_input_key(event)
+        end
+
+        # Renders the command palette as a vertically-stacked text representation: the search TextInput
+        # row on line 1, and then the filtered List results (or "No commands found") on subsequent lines.
+        # Returns a multiline string suitable for terminal rendering.
+        def render
+          [input.render, render_results].join("\n")
+        end
+
+        private
+
+        attr_reader :height, :list
+
+        # Delegates key handling entirely to the internal List widget, which manages up/down/home/end selection.
+        # Returns whatever the List's handle_key returns (typically nil or the symbol from the subclass).
+        def handle_list_key(event)
+          list.handle_key(event)
+        end
+
+        # Passes the key event to the TextInput for cursor position and search text management.
+        # If the input returns :handled, rebuilds the List so that filtering is re-evaluated against
+        # the new input value. Returns nil/nil if no handler consumed the event.
+        def handle_input_key(event)
+          result = input.handle_key(event)
+          @list = build_list if result == :handled
+          result
+        end
+
+        # Checks whether the given key is a List-navigation key (up/down/home/end). Returns true for those keys
+        # so they can be dispatched via +handle_list_key+ rather than falling through to TextInput.
+        def list_key?(key)
+          %i[up down home end enter].include?(key)
+        end
+
+        # Renders the filtered results section below the search input. If no commands match the current filter text,
+        # returns "No commands found"; otherwise renders the List widget's styled display string. Returns a single-line string.
+        def render_results
+          return "No commands found" if filtered_commands.empty?
+
+          list.render
+        end
+
+        # Builds a new List from the currently filtered commands at the given selected_index height and label extractor.
+        # The +selected_index+ parameter defaults to the last known value in +list+ to preserve scroll position across rebuilds.
+        def build_list(selected_index: list&.selected_index || 0)
+          List.new(items: filtered_commands, selected_index: selected_index, height: height, label: :label.to_proc, theme: theme)
+        end
+
+        # Returns the full commands array when input value is empty; otherwise a subset whose labels match case-insensitively
+        # against the current TextInput value. Used to drive the fuzzy search behavior. Returns an Array of Command entries.
+        def filtered_commands
+          return commands if input.value.empty?
+
+          commands.select do |command|
+            command.label.downcase.include?(input.value.downcase)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # EmptyState is a placeholder component for screens with no content. Renders one of three
+      # states: a default "nothing to show" message, a "loading…" message, or an error message
+      # with optional help text.
+      class EmptyState < Component
+        # *message* is shown in the default state. *loading* switches to the loading message
+        # (overrides *message*). *loading_message* is the string rendered in the loading state.
+        # *error* and *error_message* switch to the error state (the string form takes precedence).
+        # *help* is an optional muted line shown below the error message.
+        def initialize(message: "Nothing to show.", loading: false, loading_message: "Loading...", error: nil, error_message: nil, help: nil, theme: nil)
+          super(theme: theme)
+          @message = message
+          @loading = loading
+          @loading_message = loading_message
+          @error = error
+          @error_message = error_message
+          @help = help
+        end
+
+        # Renders the appropriate state as styled text: loading → loading message, error →
+        # error message + help, otherwise the default message.
+        def render
+          return loading_state if @loading
+          return error_state if error?
+
+          text @message, style: theme.muted
+        end
+
+        private
+
+        # Renders the loading state as a muted line.
+        def loading_state
+          text @loading_message, style: theme.muted
+        end
+
+        # Renders the error state: the error message styled with the theme's warn style,
+        # optionally followed by a muted help line.
+        def error_state
+          lines = [text(@error_message || @error.to_s, style: theme.warn)]
+          lines << text(@help, style: theme.muted) if @help.to_s.strip != ""
+
+          column(*lines)
+        end
+
+        # True when either the *error* or *error_message* string is non-blank.
+        def error?
+          @error.to_s.strip != "" || @error_message.to_s.strip != ""
+        end
+      end
+    end
+  end
+end