charming 0.1.1 → 0.1.2

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

@@ -4,9 +4,17 @@ module Charming
   module Presentation
     module Components
       class Form
+        # Field is the abstract base class for Form fields. Subclasses define `default_value`
+        # and `render_control` (or override `render`); the base class supplies validation,
+        # help-line rendering, error-line rendering, and value lookup against the form state.
         class Field < Component
+          # The field's name symbol, human-readable label, optional help text, and bound state hash.
           attr_reader :name, :label, :help, :state
 
+          # *name* is the value key (a Symbol). *label* defaults to a humanized version of *name*.
+          # *required* enables a "is required" validator. *validate* is an optional callable
+          # (returning nil/true → ok, false → "is invalid", Array → messages, anything else → stringified).
+          # *help* is an optional muted helper line rendered under the field.
           def initialize(name, label: nil, required: false, validate: nil, help: nil, theme: nil)
             super(theme: theme)
             @name = name.to_sym
@@ -16,26 +24,34 @@ module Charming
             @help = help
           end
 
+          # Binds the field to the form's *state* hash, ensuring the field's per-field state
+          # and a default value are present.
           def bind(state)
             @state = state
             state[:fields][name] ||= {}
             state[:values][name] = default_value unless state[:values].key?(name)
           end
 
+          # Subclasses that participate in Tab/Enter navigation return true. Default is true.
           def focusable?
             true
           end
 
+          # Default key handler returns nil (no key handling). Subclasses override.
           def handle_key(_event)
             nil
           end
 
+          # Renders the field as a control line prefixed with ">" (active) or " " (inactive),
+          # optionally followed by the help line and any error lines.
           def render(active: false)
             line = "#{active ? ">" : " "} #{render_control}"
             line = theme.selected.render(line) if active
             [line, help_line, *error_lines].compact.join("\n")
           end
 
+          # Returns an array of validation error messages. Includes "is required" when
+          # the field is required and blank, plus any messages produced by the user validator.
           def validate
             messages = []
             messages << "is required" if required? && blank?(value)
@@ -43,24 +59,29 @@ module Charming
             messages
           end
 
+          # The current value of this field from the bound state.
           def value
             state[:values][name]
           end
 
           private
 
+          # The default value assigned to a freshly-bound field. Subclasses override.
           def default_value
             nil
           end
 
+          # Renders the control portion (label + value). Default: "Label: <value>".
           def render_control
             "#{label}: #{value}"
           end
 
+          # True when the field was declared with `required: true`.
           def required?
             @required
           end
 
+          # True when *value* is nil, an empty string, or responds to `empty?` with true.
           def blank?(value)
             return true if value.nil?
             return value.strip.empty? if value.is_a?(String)
@@ -68,6 +89,7 @@ module Charming
             value.respond_to?(:empty?) && value.empty?
           end
 
+          # Normalizes the user validator's return value into an array of error message strings.
           def validator_messages
             result = @validator.call(value)
             case result
@@ -78,14 +100,17 @@ module Charming
             end
           end
 
+          # The muted help line (with two-space indent) when help text was given.
           def help_line
             "  #{theme.muted.render(help)}" if help
           end
 
+          # The list of error lines (with two-space indent) for any errors stored against this field.
           def error_lines
             Array(state[:errors][name]).map { |message| "  #{theme.warn.render(message)}" }
           end
 
+          # Converts a snake_case symbol/string to a humanized "Capitalized" string.
           def humanize(value)
             value.to_s.tr("_", " ").capitalize
           end

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

@@ -4,7 +4,12 @@ module Charming
   module Presentation
     module Components
       class Form
+        # Input is a single-line Form field backed by a TextInput widget. The cursor position
+        # is persisted in the form's per-field state so the field can be refocused mid-edit.
         class Input < Field
+          # *value* is the initial text. *placeholder* is shown when the value is empty.
+          # *width* optionally constrains the rendered width. All other options are forwarded
+          # to Field (label, required, validate, help, theme).
           def initialize(name, value: "", placeholder: "", width: nil, **options)
             super(name, **options)
             @initial_value = value
@@ -12,12 +17,16 @@ module Charming
             @width = width
           end
 
+          # Binds the field to the form state, sets the initial value if absent, and initializes
+          # the per-field cursor offset to the end of the value.
           def bind(state)
             super
             state[:values][name] = @initial_value if state[:values][name].nil?
             field_state[:cursor] = state[:values][name].to_s.length unless field_state.key?(:cursor)
           end
 
+          # Forwards key events to the underlying TextInput, syncing the value and cursor
+          # back into the form state. Returns :handled when the event was consumed.
           def handle_key(event)
             text_input = input
             result = text_input.handle_key(event)
@@ -30,14 +39,18 @@ module Charming
 
           private
 
+          # The default value for a freshly-bound field is the *value* passed at construction.
           def default_value
             @initial_value
           end
 
+          # Renders the field as "Label: <text input>".
           def render_control
             "#{label}: #{input.render}"
           end
 
+          # Builds a fresh TextInput each render, seeded from the current form-state value
+          # and the persisted cursor offset.
           def input
             TextInput.new(
               value: value.to_s,
@@ -47,6 +60,7 @@ module Charming
             )
           end
 
+          # Returns the per-field state hash for this field.
           def field_state
             state[:fields][name]
           end

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

@@ -4,24 +4,33 @@ module Charming
   module Presentation
     module Components
       class Form
+        # Note is a non-interactive Form field that renders a static string of text. Notes
+        # never receive focus, never validate, and store no value — they are presentational
+        # only, useful for headings, dividers, or instructional text inside a form.
         class Note < Field
+          # *text* is the literal string to render. *name* is unused (defaults to :note) and
+          # exists only because the Field base class requires a name.
           def initialize(text, name: :note, theme: nil)
             super(name, theme: theme)
             @text = text
           end
 
+          # Binds the field to the form state but does not create any per-field storage.
           def bind(state)
             @state = state
           end
 
+          # Notes are never focusable and therefore excluded from Tab/Enter traversal.
           def focusable?
             false
           end
 
+          # Notes never produce validation errors.
           def validate
             []
           end
 
+          # Returns the literal text, ignoring the *active:* flag (notes have no focus state).
           def render(active: false)
             @text.to_s
           end

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

@@ -4,7 +4,13 @@ module Charming
   module Presentation
     module Components
       class Form
+        # Select is a single-choice Form field backed by a List widget. The selected option
+        # becomes the field's value; navigation keys (up/down/home/end) cycle through options
+        # and Enter has no effect (selection is applied immediately on key release).
         class Select < Field
+          # *options* is the array of selectable values. *selected_index* defaults to 0.
+          # *option_label* is a callable used to extract the display string (default: `to_s`).
+          # All other options are forwarded to Field.
           def initialize(name, options:, selected_index: 0, option_label: :to_s.to_proc, **field_options)
             super(name, **field_options)
             @options = options
@@ -12,11 +18,14 @@ module Charming
             @option_label = option_label
           end
 
+          # Binds the field, then ensures the persisted selection (or initial/derived one) is applied.
           def bind(state)
             super
             ensure_selection
           end
 
+          # Forwards key events to the underlying List, syncing the chosen option index back
+          # into the field state. Returns :handled when consumed.
           def handle_key(event)
             selection = list
             result = selection.handle_key(event)
@@ -28,24 +37,32 @@ module Charming
 
           private
 
+          # The options array (used as the source of truth for default value and clamp).
           attr_reader :options
 
+          # The default value is the option at the clamped initial selected index.
           def default_value
             options[clamped_initial_index]
           end
 
+          # Renders the field as "Label: <display value>".
           def render_control
             "#{label}: #{display_value}"
           end
 
+          # Returns the stringified value via the configured option label callable.
           def display_value
             value.nil? ? "" : @option_label.call(value)
           end
 
+          # Builds a fresh List each render with the current options, selected index, label
+          # callable, and theme.
           def list
             List.new(items: options, selected_index: selected_index, label: @option_label, theme: theme)
           end
 
+          # Ensures the persisted selection is set, falling back to the field's initial index
+          # or the current stored value.
           def ensure_selection
             if field_state.key?(:selected_index)
               save_selection(field_state[:selected_index])
@@ -56,29 +73,35 @@ module Charming
             end
           end
 
+          # Persists the chosen *index* and the corresponding option as the field's value.
           def save_selection(index)
             field_state[:selected_index] = clamp_index(index)
             state[:values][name] = options[field_state[:selected_index]]
           end
 
+          # The currently persisted selected index (or the initial index when unset).
           def selected_index
             field_state[:selected_index] || clamped_initial_index
           end
 
+          # Clamps the initial selected index to the valid range.
           def clamped_initial_index
             clamp_index(@initial_selected_index)
           end
 
+          # Clamps *index* to the valid range. Returns 0 when there are no options.
           def clamp_index(index)
             return 0 if options.empty?
 
             index.to_i.clamp(0, options.length - 1)
           end
 
+          # Returns the index of *option* in the options array, or nil when absent.
           def index_for(option)
             options.index(option)
           end
 
+          # Returns the per-field state hash for this field.
           def field_state
             state[:fields][name]
           end

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

@@ -4,7 +4,13 @@ module Charming
   module Presentation
     module Components
       class Form
+        # Textarea is a multi-line Form field backed by a TextArea widget. The cursor offset,
+        # top-visible row, and preferred vertical column are all persisted in the form's
+        # per-field state so the field behaves consistently when refocused mid-edit.
         class Textarea < Field
+          # *value* is the initial text. *placeholder* is shown when the value is empty.
+          # *width* and *height* constrain the rendered area. All other options are forwarded
+          # to Field (label, required, validate, help, theme).
           def initialize(name, value: "", placeholder: "", width: nil, height: nil, **options)
             super(name, **options)
             @initial_value = value
@@ -13,6 +19,7 @@ module Charming
             @height = height
           end
 
+          # Binds the field, seeds the initial value, and initializes the cursor/offset state.
           def bind(state)
             super
             state[:values][name] = @initial_value if state[:values][name].nil?
@@ -20,6 +27,8 @@ module Charming
             field_state[:offset] ||= 0
           end
 
+          # Forwards key events to the underlying TextArea, syncing the value, cursor, offset,
+          # and preferred column back into the form state. Returns :handled when consumed.
           def handle_key(event)
             area = text_area
             result = area.handle_key(event)
@@ -32,6 +41,8 @@ module Charming
             :handled
           end
 
+          # Renders the field with its label on the first line, body lines indented, and
+          # optional help/error lines below.
           def render(active: false)
             label_line = "#{active ? ">" : " "} #{label}:"
             label_line = theme.selected.render(label_line) if active
@@ -40,14 +51,18 @@ module Charming
 
           private
 
+          # The default value for a freshly-bound field is the *value* passed at construction.
           def default_value
             @initial_value
           end
 
+          # Renders the multi-line body, indenting each line by two spaces.
           def body_lines
             text_area.render.lines(chomp: true).map { |line| "  #{line}" }
           end
 
+          # Builds a fresh TextArea each render, seeded from the current form-state value and
+          # the persisted cursor/offset/preferred_column.
           def text_area
             TextArea.new(
               value: value.to_s,
@@ -60,6 +75,7 @@ module Charming
             )
           end
 
+          # Returns the per-field state hash for this field.
           def field_state
             state[:fields][name]
           end

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

@@ -3,9 +3,17 @@
 module Charming
   module Presentation
     module Components
+      # Form is a multi-field form component with built-in focus traversal, validation, and
+      # submit/cancel handling. Fields are produced by `Form::Builder` (see `controller.form`)
+      # and bound to a per-form mutable state hash. Tab/Shift+Tab cycles focus through
+      # focusable fields, Enter advances to the next field (or submits on the last), Escape
+      # cancels, and Ctrl+S submits from any field.
       class Form < Component
+        # The list of field objects and the mutable state hash the form is bound to.
         attr_reader :fields, :state
 
+        # *fields* is the array of form field objects. *state* is a hash for storing field
+        # values/errors and the current focus index; usually `session[:forms][form_name]`.
         def initialize(fields:, state: nil, theme: nil)
           super(theme: theme)
           @fields = fields
@@ -14,6 +22,8 @@ module Charming
           clamp_focus
         end
 
+        # Handles key events: Escape cancels, Ctrl+S submits, Tab cycles focus, Enter advances
+        # or submits, and unhandled keys are passed to the focused field.
         def handle_key(event)
           key = Charming.key_of(event)
           return :cancelled if key == :escape
@@ -26,10 +36,12 @@ module Charming
           advance_or_submit if key == :enter
         end
 
+        # Returns a hash of `{field_name => value}` for the current field values.
         def values
           state[:values]
         end
 
+        # Renders each field on its own line, marking the active field with `active: true`.
         def render
           fields.each_with_index.map do |field, index|
             field.render(active: index == state[:focus_index])
@@ -38,6 +50,8 @@ module Charming
 
         private
 
+        # Ensures the state hash has all the required sub-keys: :values, :fields, :errors, and
+        # a sensible :focus_index default.
         def normalize_state(value)
           value[:values] ||= {}
           value[:fields] ||= {}
@@ -46,30 +60,37 @@ module Charming
           value
         end
 
+        # Binds each field to the state hash so field updates write back into `state[:values]`.
         def bind_fields
           fields.each { |field| field.bind(state) }
         end
 
+        # Forwards *event* to the currently focused field and returns its result.
         def handle_current_field(event)
           current_field&.handle_key(event)
         end
 
+        # Returns -1 for Shift+Tab (backward), +1 for plain Tab (forward).
         def tab_direction(event)
           return -1 if event.respond_to?(:shift) && event.shift
 
           +1
         end
 
+        # True when the event is the submit shortcut (Ctrl+S).
         def submit_shortcut?(event)
           Charming.key_of(event) == :s && event.respond_to?(:ctrl) && event.ctrl
         end
 
+        # On Enter: submit when the last focusable field is active, otherwise advance focus.
         def advance_or_submit
           return submit if last_focusable?
 
           move_focus(+1)
         end
 
+        # Validates all fields, focuses the first invalid one, and returns [:submitted, values]
+        # when there are no errors.
         def submit
           state[:errors] = validation_errors
           focus_first_error unless state[:errors].empty?
@@ -78,6 +99,7 @@ module Charming
           [:submitted, values.dup]
         end
 
+        # Runs each field's validator and collects per-field error messages.
         def validation_errors
           fields.each_with_object({}) do |field, errors|
             messages = field.validate
@@ -85,15 +107,18 @@ module Charming
           end
         end
 
+        # Moves focus to the first focusable field with errors, when any.
         def focus_first_error
           invalid = fields.index { |field| field.focusable? && state[:errors].key?(field.name) }
           state[:focus_index] = invalid if invalid
         end
 
+        # Returns the field at the current focus index, or nil when out of range.
         def current_field
           fields[state[:focus_index]]
         end
 
+        # Moves focus by *direction* (forward or backward) through the focusable fields.
         def move_focus(direction)
           indices = focusable_indices
           return nil if indices.empty?
@@ -103,18 +128,22 @@ module Charming
           :handled
         end
 
+        # True when the current focus index is the last focusable field.
         def last_focusable?
           focusable_indices.last == state[:focus_index]
         end
 
+        # Indices of focusable fields, memoized.
         def focusable_indices
           @focusable_indices ||= fields.each_index.select { |index| fields[index].focusable? }
         end
 
+        # The first index of a focusable field, or nil when no fields are focusable.
         def first_focusable_index
           fields.each_index.find { |index| fields[index].focusable? }
         end
 
+        # On initialization, ensures :focus_index points at a focusable field.
         def clamp_focus
           return if focusable_indices.empty?
           return if focusable_indices.include?(state[:focus_index])

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

@@ -3,6 +3,10 @@
 module Charming
   module Presentation
     module Components
+      # List is a vertically-scrollable selectable list. Supports keyboard navigation
+      # (up/down/home/end, Enter to activate) and mouse click selection. When a *height* is
+      # given, the list renders a fixed-height window over its items with auto-scroll
+      # keeping the selected item in view.
       class List < Component
         include KeyboardHandler
 
@@ -16,8 +20,13 @@ module Charming
           end: :move_end
         }.freeze
 
+        # The item array and the currently selected index within it.
         attr_reader :items, :selected_index
 
+        # *items* is the array of selectable objects. *selected_index* defaults to 0.
+        # *height* optionally constrains the visible window; *label* is a callable that
+        # extracts the display string from an item (defaults to `to_s`).
+        # *keymap* selects the keybinding style (`:vim` enables h/j/k/l → left/down/up/right).
         def initialize(items:, selected_index: 0, height: nil, label: nil, theme: nil, keymap: :vim)
           super(theme: theme)
           @items = items
@@ -28,12 +37,16 @@ module Charming
           clamp_position
         end
 
+        # Handles key events. Returns `[:selected, item]` on Enter when an item is selected;
+        # otherwise delegates to the KeyboardHandler for navigation keys.
         def handle_key(event)
           return [:selected, selected_item] if Charming.key_of(event) == :enter && selected_item
 
           super
         end
 
+        # Handles mouse events: a click within the visible window selects the clicked row.
+        # Returns :handled on a successful click, nil otherwise.
         def handle_mouse(event)
           return nil unless @height
           return nil unless event.respond_to?(:click?) && event.click?
@@ -46,10 +59,13 @@ module Charming
           :handled
         end
 
+        # Returns the currently selected item, or nil when the list is empty.
         def selected_item
           items[selected_index]
         end
 
+        # Renders the visible window of items, prefixing each with "> " (and applying the
+        # selected style) or "  ".
         def render
           visible_items.each_with_index.map do |item, index|
             render_item(item, viewport_start + index)
@@ -58,42 +74,54 @@ module Charming
 
         private
 
+        # Moves the selection up one position.
         def move_up
           @selected_index -= 1 if selected_index.positive?
         end
 
+        # Moves the selection down one position.
         def move_down
           @selected_index += 1 if selected_index < items.length - 1
         end
 
+        # Moves the selection to the first item.
         def move_home
           @selected_index = 0
         end
 
+        # Moves the selection to the last item (no-op when the list is empty).
         def move_end
           @selected_index = items.length - 1 unless items.empty?
         end
 
+        # Returns the slice of items currently in the visible window.
         def visible_items
           items[viewport_start, viewport_height] || []
         end
 
+        # Returns the index of the topmost visible item, computed so the selected item stays
+        # in view when the list is taller than the visible window.
         def viewport_start
           return 0 unless @height
 
           Layout.selected_window_start(selected_index: selected_index, item_count: items.length, window_size: @height)
         end
 
+        # Returns the number of items visible in the window (the configured *height* or the
+        # total item count when no height was set).
         def viewport_height
           @height || items.length
         end
 
+        # Renders a single item: prefix with "> " (selected) or "  " (unselected), then apply
+        # the theme's selected style to the selected item's row.
         def render_item(item, index)
           prefix = (index == selected_index) ? "> " : "  "
           rendered = "#{prefix}#{@label.call(item)}"
           (index == selected_index) ? theme.selected.render(rendered) : rendered
         end
 
+        # Resets the selection when the list is empty, otherwise clamps it to the valid range.
         def clamp_position
           @selected_index = 0 if items.empty?
           @selected_index = selected_index.clamp(0, items.length - 1) unless items.empty?

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

@@ -3,7 +3,12 @@
 module Charming
   module Presentation
     module Components
+      # Markdown renders Markdown source as ANSI-styled terminal text. Parsing is delegated to
+      # `Presentation::Markdown::Renderer`; set *syntax_highlighting* to false to disable
+      # Rouge-backed code block highlighting.
       class Markdown < Component
+        # *content* is the Markdown source string. *width* optionally sets the wrap width.
+        # *syntax_highlighting* enables Rouge for code blocks (defaults to true).
         def initialize(content:, width: nil, theme: nil, syntax_highlighting: true)
           super(theme: theme)
           @content = content
@@ -11,6 +16,7 @@ module Charming
           @syntax_highlighting = syntax_highlighting
         end
 
+        # Renders the Markdown body to a styled, terminal-safe string.
         def render
           Charming::Presentation::Markdown::Renderer.new(
             content: @content,

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

@@ -3,7 +3,13 @@
 module Charming
   module Presentation
     module Components
+      # Modal is a centered, boxed overlay with an optional title, help line, and body content.
+      # The body may be a string, View, or Component; when it responds to `render`, its output
+      # is used. The result is wrapped in a UI::Style border with padding.
       class Modal < Component
+        # *content* is the modal body. *title* (optional) is rendered centered at the top.
+        # *help* (optional) is rendered as a muted footer line. *width* is the modal's total width.
+        # *style* overrides the default `theme.modal` style.
         def initialize(content:, title: nil, help: nil, width: 52, style: nil, theme: nil)
           super(theme: theme)
           @content = content
@@ -13,6 +19,8 @@ module Charming
           @style = style
         end
 
+        # Renders the modal as a bordered, padded string with the title and help lines stacked
+        # above the content.
         def render
           box(column(*lines, gap: 1), style: modal_style)
         end
@@ -21,26 +29,32 @@ module Charming
 
         attr_reader :content, :title, :help, :width
 
+        # Returns the array of non-nil lines: title, help, content.
         def lines
           [title_line, help_line, render_content].compact
         end
 
+        # Returns the centered title line styled with the theme's title style, when a title was given.
         def title_line
           text(title, style: theme.title.align(:center).width(title_width)) if title
         end
 
+        # Returns the help line styled with the theme's muted style, when help was given.
         def help_line
           text(help, style: theme.muted) if help
         end
 
+        # Returns the rendered content string, calling `render` on the body when applicable.
         def render_content
           content.respond_to?(:render) ? render_component(content) : content.to_s
         end
 
+        # Returns the modal's outer style: the user-provided style or `theme.modal` at the given width.
         def modal_style
           @style || theme.modal.width(width)
         end
 
+        # Returns the title's display width, accounting for the modal's horizontal padding/border.
         def title_width
           [width - 8, 0].max
         end