charming 0.1.1 → 0.1.2

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

@@ -3,11 +3,21 @@
 module Charming
   module Internal
     module Terminal
+      # MemoryBackend is an in-memory implementation of the terminal Adapter used by
+      # RSpec specs. It serves events from a fixed `events:` list and records every
+      # output operation in `frames` (rendered output) and `operations` (every method
+      # call with its arguments), so tests can assert against observed output.
       class MemoryBackend
         include Adapter
 
-        attr_reader :frames, :operations
+        # The array of rendered frame strings (one per `write_frame` or `write_lines` call).
+        attr_reader :frames
 
+        # The array of recorded operation tuples: [:method_name, *args].
+        attr_reader :operations
+
+        # *events* is the queue of pre-seeded events to return from `read_event`.
+        # *width*/*height* set the initial terminal dimensions reported by `size`.
         def initialize(events: [], width: 80, height: 24)
           @events = events.dup
           @width = width
@@ -17,67 +27,84 @@ module Charming
           @mouse_enabled = false
         end
 
+        # Pops the next pre-seeded event from the queue. Returns nil when the queue is empty.
         def read_event(timeout: nil)
           @operations << [:read_event, timeout]
           @events.shift
         end
 
+        # Stores *frame* as the current frame and appends it to `frames`.
         def write_frame(frame)
           @current_frame = frame
           @frames << frame
           @operations << [:write_frame, frame]
         end
 
+        # Applies the [row, line] *line_changes* to the current frame, then stores and
+        # records the result. The full frame is taken from the optional *frame:* argument
+        # (when provided) or built by overlaying the changes on the previous frame.
         def write_lines(line_changes, frame: nil)
           @current_frame = frame || apply_line_changes(line_changes)
           @frames << @current_frame
           @operations << [:write_lines, line_changes]
         end
 
+        # Records an enter-alt-screen operation.
         def enter_alt_screen
           @operations << :enter_alt_screen
         end
 
+        # Records a leave-alt-screen operation.
         def leave_alt_screen
           @operations << :leave_alt_screen
         end
 
+        # Records a show-cursor operation.
         def show_cursor
           @operations << :show_cursor
         end
 
+        # Records a hide-cursor operation.
         def hide_cursor
           @operations << :hide_cursor
         end
 
+        # Records a clear-screen operation.
         def clear
           @operations << :clear
         end
 
+        # Records a move-cursor operation at the given (row, column) (1-based).
         def move_cursor(row, column)
           @operations << [:move_cursor, row, column]
         end
 
+        # Returns the configured terminal dimensions as [width, height].
         def size
           [@width, @height]
         end
 
+        # Marks the backend as having mouse tracking enabled and records the operation.
         def enable_mouse_tracking
           @mouse_enabled = true
           @operations << :enable_mouse_tracking
         end
 
+        # Marks the backend as having mouse tracking disabled and records the operation.
         def disable_mouse_tracking
           @mouse_enabled = false
           @operations << :disable_mouse_tracking
         end
 
+        # Returns whether mouse tracking is currently enabled.
         def mouse_enabled?
           @mouse_enabled
         end
 
         private
 
+        # Overlays each [row, line] from *line_changes* onto a copy of the current frame
+        # (1-based row indexing). Used when `write_lines` is called without a *frame:* argument.
         def apply_line_changes(line_changes)
           lines = @current_frame.to_s.lines(chomp: true)
           line_changes.each do |row, line|

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    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.
+      class MouseParser
+        # Matches an SGR-encoded mouse sequence: "\e[<button;col;row[mode]M"
+        SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)([HmMhCc]?)(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
+
+        # Returns true when *raw* looks like a recognizable mouse sequence (SGR or legacy).
+        # Lets the TTYBackend short-circuit and dispatch to MouseParser without allocation.
+        def self.sequence?(raw)
+          return false unless raw.is_a?(String)
+          return true if raw.match?(SGR_PATTERN)
+          return true if raw.start_with?("\e[M")
+
+          false
+        end
+
+        # Parses *raw* into a MouseEvent, or returns nil when the string is not a mouse
+        # sequence or cannot be decoded.
+        def self.parse(raw)
+          return nil unless raw.is_a?(String)
+          return parse_sgr(raw) if raw.match?(SGR_PATTERN)
+          return parse_legacy(raw) if raw.start_with?("\e[M")
+
+          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.
+        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)
+        end
+
+        # Parses a legacy 3-byte mouse sequence. Each of the 3 bytes has 32 subtracted
+        # to recover the (button, col, row) values.
+        def self.parse_legacy(raw)
+          match = raw.match(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
+
+          Events::MouseEvent.new(button: button_code, x: col, y: row)
+        end
+      end
+    end
+  end
+end

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

@@ -7,65 +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"
+
+        # Escape sequences for disabling/enabling automatic line wrapping during frame writes.
         AUTO_WRAP_OFF = "\e[?7l"
         AUTO_WRAP_ON = "\e[?7h"
-        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
 
+        # *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
 
@@ -75,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
 
@@ -85,175 +99,91 @@ 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)
           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, **)
           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"
-
-          Events::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
-
-          Events::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
           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)
-          Events::KeyEvent.new(key: keypress.to_sym, char: keypress)
-        end
-
-        def named_event(key_name)
-          normalized = normalize_key_name(key_name)
-          Events::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}
-        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
-        end
-
+        # Writes a raw escape *sequence* to the output stream and flushes.
         def write_control(sequence)
           @output.write(sequence)
           @output.flush
         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
 
+        # Disables auto-wrap, yields, then re-enables it and flushes the output.
         def without_auto_wrap
           @output.write(AUTO_WRAP_OFF)
           yield

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

@@ -3,7 +3,14 @@
 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
@@ -14,6 +21,8 @@ module Charming
           @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?
@@ -23,10 +32,13 @@ module Charming
 
         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 != ""
@@ -34,6 +46,7 @@ module Charming
           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

data/lib/charming/presentation/components/form/builder.rb

@@ -4,40 +4,54 @@ module Charming
   module Presentation
     module Components
       class Form
+        # Builder collects form field declarations inside a `form(:name) { ... }` block and
+        # assembles them into a Form component when `build` is called. Each declaration method
+        # appends a Field subclass instance to the builder's *fields* list.
         class Builder
+          # The accumulated field list and the theme applied to each declared field.
           attr_reader :fields, :theme
 
+          # Initializes an empty builder. *theme* is forwarded to every declared field unless
+          # the field declaration explicitly overrides it.
           def initialize(theme: nil)
             @theme = theme
             @fields = []
           end
 
+          # Appends a single-line Input field. *options* are passed through to Input.
           def input(name, **options)
             fields << Input.new(name, **field_options(options))
           end
 
+          # Appends a multi-line Textarea field.
           def textarea(name, **options)
             fields << Textarea.new(name, **field_options(options))
           end
 
+          # Appends a Select field with the given *options* array.
           def select(name, **options)
             fields << Select.new(name, **field_options(options))
           end
 
+          # Appends a Confirm (boolean) field.
           def confirm(name, **options)
             fields << Confirm.new(name, **field_options(options))
           end
 
+          # Appends a static Note (non-focusable).
           def note(text, **options)
             fields << Note.new(text, **field_options(options))
           end
 
+          # Assembles the collected fields into a Form component, bound to *state* and using
+          # the *theme* argument (falling back to the builder's theme).
           def build(state:, theme: nil)
             Components::Form.new(fields: fields, state: state, theme: theme || self.theme)
           end
 
           private
 
+          # Merges the builder's theme into the per-field *options* so each field receives it.
           def field_options(options)
             {theme: theme}.merge(options)
           end

data/lib/charming/presentation/components/form/confirm.rb

@@ -4,12 +4,19 @@ module Charming
   module Presentation
     module Components
       class Form
+        # Confirm is a boolean Form field that renders a checkbox-style control. Space toggles
+        # the value; y/Right sets it to true; n/Left sets it to false. Required confirms must
+        # be accepted (value == true) to pass validation.
         class Confirm < Field
+          # *value* is the initial boolean state (default: false). All other options are
+          # forwarded to Field.
           def initialize(name, value: false, **options)
             super(name, **options)
             @initial_value = value
           end
 
+          # Handles the standard confirm keys: space toggles, y/right sets to true, n/left
+          # sets to false, and a space character (when the event exposes `char`) also toggles.
           def handle_key(event)
             case Charming.key_of(event)
             when :space
@@ -26,6 +33,8 @@ module Charming
             :handled
           end
 
+          # Returns ["must be accepted"] when required and the value is not true, otherwise
+          # the result of the base Field validation.
           def validate
             return ["must be accepted"] if required? && value != true
 
@@ -34,18 +43,22 @@ module Charming
 
           private
 
+          # The default value for a freshly-bound field is the *value* passed at construction.
           def default_value
             @initial_value
           end
 
+          # Renders "[x] Label" or "[ ] Label" depending on the current value.
           def render_control
             "#{checked_marker} #{label}"
           end
 
+          # Returns the checkbox marker string.
           def checked_marker
             value ? "[x]" : "[ ]"
           end
 
+          # Flips the current value (true ↔ false).
           def toggle
             state[:values][name] = !value
           end