charming 0.1.1 → 0.1.2

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

@@ -3,9 +3,17 @@
 module Charming
   module Presentation
     module Components
+      # Progressbar renders a fixed-width ASCII progress bar. The bar is sized to the configured
+      # *total* (in arbitrary units) and fills proportionally to the current value. Optionally
+      # appends a label after the bar.
       class Progressbar < Component
+        # Public accessors: total units, current value, label text, completed and remaining
+        # characters, and the bar format symbol.
         attr_accessor :total, :current, :label, :complete, :incomplete, :bar_format
 
+        # *total* is the maximum unit count. *complete* and *incomplete* are the characters used
+        # for filled and unfilled positions (default "=" and " "). *bar_format* is reserved for
+        # future format variants. *label* is an optional suffix shown after the bar.
         def initialize(total:, complete: "=", incomplete: " ", bar_format: :classic, label: nil)
           super()
           @total = [total.to_i, 0].max
@@ -16,21 +24,25 @@ module Charming
           @current = 0
         end
 
+        # Advances the current value by *count* (default 1), clamping to `[0, total]`. Returns self.
         def tick(count = 1)
           update(@current + count)
           self
         end
 
+        # Sets the current value, clamping to `[0, total]`. Returns self.
         def update(value)
           @current = value.to_i.clamp(0, @total)
           self
         end
 
+        # Jumps the bar directly to 100% completion. Returns self.
         def complete!
           @current = @total
           self
         end
 
+        # Renders the bar as `[====  ]` (with the *label* appended when present).
         def render
           width = [@total, 1].max
           completed = completed_width(width)
@@ -46,6 +58,7 @@ module Charming
 
         private
 
+        # Returns the number of `complete` characters to draw, rounded to the nearest integer.
         def completed_width(width)
           return 0 unless @total.positive?
 

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

@@ -3,11 +3,18 @@
 module Charming
   module Presentation
     module Components
+      # Spinner is a simple rotating-frame indicator. The component cycles through a list of
+      # frames on each `tick`; pair it with a controller timer to drive animation. An optional
+      # *label* is appended after the current frame on each render.
       class Spinner < Component
+        # The default frame set: a 4-frame ASCII spinner.
         DEFAULT_FRAMES = ["-", "\\", "|", "/"].freeze
 
+        # The current frame list, frame index, and optional label string.
         attr_reader :frames, :index, :label
 
+        # *frames* defaults to DEFAULT_FRAMES but may be replaced with any array of frame strings.
+        # *index* is the starting frame index. *label* is an optional suffix shown after the frame.
         def initialize(frames: DEFAULT_FRAMES, index: 0, label: nil)
           super()
           raise ArgumentError, "frames cannot be empty" if frames.empty?
@@ -17,11 +24,13 @@ module Charming
           @label = label
         end
 
+        # Advances the frame index by one position, wrapping around. Returns self for chaining.
         def tick
           @index = (index + 1) % frames.length
           self
         end
 
+        # Renders the current frame, optionally followed by the label and a space.
         def render
           return frame unless label
 
@@ -30,6 +39,7 @@ module Charming
 
         private
 
+        # Returns the current frame string (with index modulo frame count to be safe).
         def frame
           frames.fetch(index % frames.length)
         end

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

@@ -5,9 +5,14 @@ require "tty-table"
 module Charming
   module Presentation
     module Components
+      # Table renders tabular data with a header row, a selected row highlight, and keyboard
+      # navigation. Mouse clicks within the body area also select rows. The table is rendered
+      # via tty-table and the selected row is overlaid with reverse-video ANSI styling.
       class Table < Component
         include KeyboardHandler
 
+        # Maps navigation keys to the instance methods that move the selection. Shared with
+        # List and Viewport via KeyboardHandler.
         KEY_ACTIONS = {
           up: :move_up,
           down: :move_down,
@@ -15,10 +20,16 @@ module Charming
           end: :move_end
         }.freeze
 
+        # Number of terminal rows occupied by the table's top border and header line. Used by
+        # the mouse handler to translate absolute row coordinates to body rows.
         HEADER_HEIGHT = 2
 
+        # The header row, the body rows, and the currently selected row index, respectively.
         attr_reader :header, :rows, :selected_index
 
+        # *header* is an array of column labels. *rows* is the array of body rows (each either a
+        # String, an Array, or a Hash of column-value pairs). *selected_index* defaults to 0.
+        # *keymap* selects the keybinding style (`:vim` enables h/j/k/l → left/down/up/right).
         def initialize(header:, rows: [], selected_index: 0, keymap: :vim)
           super()
           @header = Array(header).map(&:to_s)
@@ -27,6 +38,8 @@ module Charming
           @keymap = keymap
         end
 
+        # Handles key events. Returns `[:selected, row]` on Enter; otherwise delegates to the
+        # KeyboardHandler for navigation keys.
         def handle_key(event)
           return nil if rows.empty?
 
@@ -36,6 +49,8 @@ module Charming
           end
         end
 
+        # Handles mouse events: a click within the body area selects the clicked row.
+        # Returns :handled on a successful click.
         def handle_mouse(event)
           return nil if rows.empty?
           return nil unless event.respond_to?(:click?) && event.click?
@@ -47,10 +62,12 @@ module Charming
           :handled
         end
 
+        # Returns the currently selected row, or nil when the table is empty.
         def selected_row
           rows[selected_index]
         end
 
+        # Renders the table to a string. Returns a placeholder when both header and rows are empty.
         def render
           return "(empty table)" if header.empty? && rows.empty?
 
@@ -64,6 +81,8 @@ module Charming
 
         private
 
+        # Coerces a *row* (Hash / String / Array) into a flat cell array matching the header.
+        # Excess cells are merged into the last column with a space separator.
         def normalize_row(row)
           cells = case row
           when Hash then row.values
@@ -77,6 +96,7 @@ module Charming
           kept + [merged]
         end
 
+        # Applies the selected-row highlight and trims unused body rows below the actual row count.
         def compact_layout(lines)
           return lines.join("\n") if lines.length < 4
 
@@ -91,22 +111,27 @@ module Charming
           [top, header_line, *highlighted, bottom].compact.join("\n")
         end
 
+        # Moves the selection up one row.
         def move_up
           @selected_index -= 1 if selected_index.positive?
         end
 
+        # Moves the selection down one row.
         def move_down
           @selected_index += 1 if selected_index < rows.length - 1
         end
 
+        # Moves the selection to the first row.
         def move_home
           @selected_index = 0
         end
 
+        # Moves the selection to the last row.
         def move_end
           @selected_index = rows.length - 1
         end
 
+        # Clamps *value* to the valid row range, defaulting to 0 when the table is empty.
         def clamp_index(value)
           return 0 if rows.empty?
 

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

@@ -3,9 +3,19 @@
 module Charming
   module Presentation
     module Components
+      # TextArea is a multi-line text editor component. Supports character insertion (with
+      # newline insertion via Shift+Enter or Ctrl+J), cursor movement (left/right/up/down,
+      # home/end, page up/down), deletion (backspace/delete), and scrolling for long buffers.
+      # Vertical movement preserves a "preferred column" so left/right navigation feels stable.
       class TextArea < Component
+        # The current text value, cursor byte offset, top-visible row offset, and remembered
+        # column for vertical navigation, respectively.
         attr_reader :value, :cursor, :offset, :preferred_column
 
+        # *value* is the initial text. *placeholder* is shown when the value is empty. *width* and
+        # *height* constrain the rendered output. *cursor* defaults to the end of the value.
+        # *offset* is the top-visible row. *preferred_column* is the column to resume at on
+        # vertical movement (defaults to the current column on first use).
         def initialize(value: "", placeholder: "", width: nil, height: nil, cursor: nil, offset: 0, preferred_column: nil)
           super()
           @value = value.dup
@@ -19,6 +29,8 @@ module Charming
           ensure_cursor_visible
         end
 
+        # Routes key events to the appropriate cursor/text mutation. Returns :handled when the
+        # event was consumed, nil otherwise.
         def handle_key(event)
           key = Charming.key_of(event)
           return :handled if newline_event?(event) && insert("\n")
@@ -41,6 +53,8 @@ module Charming
           :handled
         end
 
+        # Renders the visible portion of the text buffer (scrolled to `offset`), with each
+        # visible line either clipped to `width` or padded to it.
         def render
           visible_lines.map { |line| render_line(line) }.join("\n")
         end
@@ -49,6 +63,7 @@ module Charming
 
         attr_reader :placeholder, :width, :height
 
+        # True when the event represents an explicit newline request: Shift+Enter or Ctrl+J.
         def newline_event?(event)
           key = Charming.key_of(event)
           return true if key == :enter && event.respond_to?(:shift) && event.shift
@@ -57,14 +72,18 @@ module Charming
           false
         end
 
+        # True when *event* carries a single printable character.
         def character_event?(event)
           event.respond_to?(:char) && event.char && event.char.length == 1 && printable?(event.char)
         end
 
+        # True when *char* is not a control character.
         def printable?(char)
           !char.match?(/[[:cntrl:]]/)
         end
 
+        # Inserts *text* at the cursor, advances the cursor by its length, resets the preferred
+        # column, and ensures the cursor remains visible.
         def insert(text)
           @value = value[0...cursor].to_s + text + value[cursor..].to_s
           @cursor += text.length
@@ -72,26 +91,31 @@ module Charming
           ensure_cursor_visible
         end
 
+        # Moves the cursor one character left.
         def move_left
           @cursor -= 1 if cursor.positive?
           reset_preferred_column
           ensure_cursor_visible
         end
 
+        # Moves the cursor one character right.
         def move_right
           @cursor += 1 if cursor < value.length
           reset_preferred_column
           ensure_cursor_visible
         end
 
+        # Moves the cursor up one line while preserving the preferred column.
         def move_up
           move_vertical(-1)
         end
 
+        # Moves the cursor down one line while preserving the preferred column.
         def move_down
           move_vertical(+1)
         end
 
+        # Moves the cursor to the start of the current line.
         def move_home
           row, = cursor_position
           @cursor = line_start(row)
@@ -99,6 +123,7 @@ module Charming
           ensure_cursor_visible
         end
 
+        # Moves the cursor to the end of the current line.
         def move_end
           row, = cursor_position
           @cursor = line_start(row) + line_length(row)
@@ -106,6 +131,7 @@ module Charming
           ensure_cursor_visible
         end
 
+        # Deletes the character before the cursor (backspace behavior).
         def delete_before_cursor
           return if cursor.zero?
 
@@ -115,6 +141,7 @@ module Charming
           ensure_cursor_visible
         end
 
+        # Deletes the character at the cursor (delete-key behavior).
         def delete_at_cursor
           return if cursor >= value.length
 
@@ -123,16 +150,20 @@ module Charming
           ensure_cursor_visible
         end
 
+        # Scrolls the buffer up by one viewport height.
         def page_up
           @offset -= viewport_height
           clamp_offset
         end
 
+        # Scrolls the buffer down by one viewport height.
         def page_down
           @offset += viewport_height
           clamp_offset
         end
 
+        # Moves the cursor vertically by *delta* rows. Stays within the line count and uses
+        # `preferred_column` so up/down movement feels stable on short lines.
         def move_vertical(delta)
           row, column = cursor_position
           target_row = (row + delta).clamp(0, lines.length - 1)
@@ -141,10 +172,13 @@ module Charming
           ensure_cursor_visible
         end
 
+        # Sets the preferred column to the current column (called when horizontal movement happens).
         def reset_preferred_column
           @preferred_column = cursor_position.last
         end
 
+        # Returns the cursor's current position as `[row, column]`, where row is the zero-based
+        # line index and column is the character offset within that line.
         def cursor_position
           before = value[0...cursor].to_s
           row = before.count("\n")
@@ -153,24 +187,30 @@ module Charming
           [row, column]
         end
 
+        # Returns the byte offset where line *row* begins in the value.
         def line_start(row)
           lines.first(row).sum(&:length) + row
         end
 
+        # Returns the character length of the line at *row* (empty string when row is past the end).
         def line_length(row)
           lines.fetch(row, "").length
         end
 
+        # Splits the value into an array of lines (preserving trailing empty lines).
         def lines
           value.empty? ? [""] : value.split("\n", -1)
         end
 
+        # Returns the rendered lines (with cursor marker inserted) before viewport slicing.
         def rendered_lines
           return [cursor_marker + placeholder] if value.empty?
 
           (value[0...cursor].to_s + cursor_marker + value[cursor..].to_s).split("\n", -1)
         end
 
+        # Returns the lines that should be visible in the current viewport, padded to *height*
+        # with empty strings when the buffer is shorter.
         def visible_lines
           ensure_cursor_visible
           rendered = rendered_lines.slice(offset, viewport_height) || []
@@ -179,6 +219,7 @@ module Charming
           rendered + Array.new([height - rendered.length, 0].max, "")
         end
 
+        # Renders a single line, clipping to *width* and padding with spaces.
         def render_line(line)
           return line unless width
 
@@ -186,6 +227,8 @@ module Charming
           clipped + (" " * [width - UI::Width.measure(clipped), 0].max)
         end
 
+        # Adjusts the top-visible offset so the cursor row is in view. Scrolling is performed
+        # one row at a time when needed.
         def ensure_cursor_visible
           row, = cursor_position
           @offset = row if row < offset
@@ -193,23 +236,28 @@ module Charming
           clamp_offset
         end
 
+        # Clamps the cursor and offset to valid bounds.
         def clamp_position
           @cursor = cursor.clamp(0, value.length)
           clamp_offset
         end
 
+        # Clamps the offset to the valid range `[0, max_offset]`.
         def clamp_offset
           @offset = offset.clamp(0, max_offset)
         end
 
+        # Returns the maximum allowed offset (so the bottom of the buffer is reachable).
         def max_offset
           [lines.length - viewport_height, 0].max
         end
 
+        # Returns the visible row count (the configured *height* or the buffer's line count).
         def viewport_height
           height || lines.length
         end
 
+        # The literal character used to mark the cursor position in `rendered_lines`.
         def cursor_marker
           "|"
         end

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

@@ -3,6 +3,10 @@
 module Charming
   module Presentation
     module Components
+      # TextInput is a single-line text editor component. Supports printable character insertion,
+      # cursor movement (left/right/home/end), and deletion (backspace/delete). The component
+      # exposes its `value` and `cursor` positions as reader methods; when an explicit `width:`
+      # is given, the rendered output is padded to that width via a UI::Style.
       class TextInput < Component
         include KeyboardHandler
 
@@ -18,8 +22,11 @@ module Charming
           delete: :delete_at_cursor
         }.freeze
 
+        # The current input string and the byte offset of the cursor within it.
         attr_reader :value, :cursor
 
+        # *value* is the initial text. *placeholder* is shown when the value is empty.
+        # *width* optionally constrains the rendered output width; *cursor* defaults to the end.
         def initialize(value: "", placeholder: "", width: nil, cursor: nil)
           super()
           @value = value.dup
@@ -29,12 +36,16 @@ module Charming
           clamp_position
         end
 
+        # Handles key events. Inserts printable characters, otherwise dispatches via KEY_ACTIONS.
+        # Returns :handled when the event was consumed, nil otherwise.
         def handle_key(event)
           return :handled if character_event?(event) && insert(event.char)
 
           super
         end
 
+        # Renders the value with a cursor marker. When *width* was given at construction, the
+        # output is padded to that width via the configured style.
         def render
           rendered = render_value
           @width ? style.width(@width).render(rendered) : rendered
@@ -44,35 +55,43 @@ module Charming
 
         attr_reader :placeholder
 
+        # True when *event* carries a single printable character that should be inserted.
         def character_event?(event)
           event.respond_to?(:char) && event.char && event.char.length == 1 && printable?(event.char)
         end
 
+        # True when *char* is not a control character (and therefore safe to insert).
         def printable?(char)
           !char.match?(/[[:cntrl:]]/)
         end
 
+        # Inserts *char* at the cursor and advances the cursor by its byte length.
         def insert(char)
           @value = value[0...cursor] + char + value[cursor..]
           @cursor += char.length
         end
 
+        # Moves the cursor one position left, when possible.
         def move_left
           @cursor -= 1 if cursor.positive?
         end
 
+        # Moves the cursor one position right, when possible.
         def move_right
           @cursor += 1 if cursor < value.length
         end
 
+        # Moves the cursor to the start of the value.
         def move_home
           @cursor = 0
         end
 
+        # Moves the cursor to the end of the value.
         def move_end
           @cursor = value.length
         end
 
+        # Deletes the character before the cursor (backspace behavior).
         def delete_before_cursor
           return if cursor.zero?
 
@@ -80,22 +99,27 @@ module Charming
           @cursor -= 1
         end
 
+        # Deletes the character at the cursor (delete-key behavior).
         def delete_at_cursor
           return if cursor >= value.length
 
           @value = value[0...cursor] + value[(cursor + 1)..]
         end
 
+        # Renders the value with a "|" cursor marker at the current position. When the value is
+        # empty, the placeholder is rendered instead, preceded by the cursor marker.
         def render_value
           return cursor_marker + placeholder if value.empty?
 
           value[0...cursor] + cursor_marker + value[cursor..]
         end
 
+        # The literal character used to mark the cursor position in `render`.
         def cursor_marker
           "|"
         end
 
+        # Clamps the cursor to the valid range `[0, value.length]`.
         def clamp_position
           @cursor = cursor.clamp(0, value.length)
         end