charming 0.1.1 → 0.1.3

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

@@ -1,56 +1,54 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      # KeyboardHandler is a mixin module that provides keyboard event dispatch by mapping symbolic key names
-      # to private method calls. Implementors must define a constant +KEY_ACTIONS+ as a hash where each key is
-      # a symbol (e.g., :up, :down, :enter) and each value is the target method name (e.g., :move_up). Call
-      # +handle_key(event)+ with any event object; it uses Charming.key_of to resolve the raw event to a symbol,
-      # looks up the corresponding action in KEY_ACTIONS, sends that method on self, and returns :handled if an
-      # action was found. Returns nil (via :handled being truthy or not) when no matching key exists.
-      module KeyboardHandler
-        VIM_KEYMAP = {
-          up: :k,
-          down: :j,
-          left: :h,
-          right: :l
-        }.freeze
-
-        def handle_key(event)
-          key = Charming.key_of(event)
-          action = key_actions[key]
-          return unless action
-
-          send(action)
-          :handled
-        end
+  module Components
+    # KeyboardHandler is a mixin module that provides keyboard event dispatch by mapping symbolic key names
+    # to private method calls. Implementors must define a constant +KEY_ACTIONS+ as a hash where each key is
+    # a symbol (e.g., :up, :down, :enter) and each value is the target method name (e.g., :move_up). Call
+    # +handle_key(event)+ with any event object; it uses Charming.key_of to resolve the raw event to a symbol,
+    # looks up the corresponding action in KEY_ACTIONS, sends that method on self, and returns :handled if an
+    # action was found. Returns nil (via :handled being truthy or not) when no matching key exists.
+    module KeyboardHandler
+      VIM_KEYMAP = {
+        up: :k,
+        down: :j,
+        left: :h,
+        right: :l
+      }.freeze
+
+      def handle_key(event)
+        key = Charming.key_of(event)
+        action = key_actions[key]
+        return unless action
+
+        send(action)
+        :handled
+      end
 
-        private
+      private
 
-        def key_actions
-          base_key_actions.merge(normalized_keymap)
-        end
+      def key_actions
+        base_key_actions.merge(normalized_keymap)
+      end
 
-        def base_key_actions
-          self.class.const_get(:KEY_ACTIONS)
-        end
+      def base_key_actions
+        self.class.const_get(:KEY_ACTIONS)
+      end
 
-        def normalized_keymap
-          resolved_keymap.each_with_object({}) do |(action_key, keys), actions|
-            action = base_key_actions[action_key.to_sym]
-            next unless action
+      def normalized_keymap
+        resolved_keymap.each_with_object({}) do |(action_key, keys), actions|
+          action = base_key_actions[action_key.to_sym]
+          next unless action
 
-            Array(keys).each { |key| actions[key.to_sym] = action }
-          end
+          Array(keys).each { |key| actions[key.to_sym] = action }
         end
+      end
 
-        def resolved_keymap
-          case @keymap
-          when :vim then VIM_KEYMAP
-          when nil then {}
-          else @keymap
-          end
+      def resolved_keymap
+        case @keymap
+        when :vim then VIM_KEYMAP
+        when nil then {}
+        else @keymap
         end
       end
     end

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

@@ -1,103 +1,129 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class List < Component
-        include KeyboardHandler
-
-        # Maps navigation key symbols to instance methods consumed by the KeyboardHandler
-        # mixin: :up moves selection up, :down moves down, :home jumps to first item,
-        # :end jumps to last. See Viewport#KEY_ACTIONS and Table#KEY_ACTIONS for identical pattern.
-        KEY_ACTIONS = {
-          up: :move_up,
-          down: :move_down,
-          home: :move_home,
-          end: :move_end
-        }.freeze
-
-        attr_reader :items, :selected_index
-
-        def initialize(items:, selected_index: 0, height: nil, label: nil, theme: nil, keymap: :vim)
-          super(theme: theme)
-          @items = items
-          @selected_index = selected_index
-          @height = height
-          @label = label || :to_s.to_proc
-          @keymap = keymap
-          clamp_position
-        end
-
-        def handle_key(event)
-          return [:selected, selected_item] if Charming.key_of(event) == :enter && selected_item
-
-          super
-        end
-
-        def handle_mouse(event)
-          return nil unless @height
-          return nil unless event.respond_to?(:click?) && event.click?
-
-          clicked = event.y
-          return nil if clicked.negative? || clicked >= visible_items.length
-
-          @selected_index = viewport_start + clicked
-          clamp_position
-          :handled
-        end
-
-        def selected_item
-          items[selected_index]
-        end
-
-        def render
-          visible_items.each_with_index.map do |item, index|
-            render_item(item, viewport_start + index)
-          end.join("\n")
-        end
-
-        private
-
-        def move_up
-          @selected_index -= 1 if selected_index.positive?
-        end
-
-        def move_down
-          @selected_index += 1 if selected_index < items.length - 1
-        end
-
-        def move_home
-          @selected_index = 0
-        end
-
-        def move_end
-          @selected_index = items.length - 1 unless items.empty?
-        end
-
-        def visible_items
-          items[viewport_start, viewport_height] || []
-        end
-
-        def viewport_start
-          return 0 unless @height
-
-          Layout.selected_window_start(selected_index: selected_index, item_count: items.length, window_size: @height)
-        end
-
-        def viewport_height
-          @height || items.length
-        end
-
-        def render_item(item, index)
-          prefix = (index == selected_index) ? "> " : "  "
-          rendered = "#{prefix}#{@label.call(item)}"
-          (index == selected_index) ? theme.selected.render(rendered) : rendered
-        end
-
-        def clamp_position
-          @selected_index = 0 if items.empty?
-          @selected_index = selected_index.clamp(0, items.length - 1) unless items.empty?
-        end
+  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
+
+      # Maps navigation key symbols to instance methods consumed by the KeyboardHandler
+      # mixin: :up moves selection up, :down moves down, :home jumps to first item,
+      # :end jumps to last. See Viewport#KEY_ACTIONS and Table#KEY_ACTIONS for identical pattern.
+      KEY_ACTIONS = {
+        up: :move_up,
+        down: :move_down,
+        home: :move_home,
+        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
+        @selected_index = selected_index
+        @height = height
+        @label = label || :to_s.to_proc
+        @keymap = keymap
+        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?
+
+        clicked = event.y
+        return nil if clicked.negative? || clicked >= visible_items.length
+
+        @selected_index = viewport_start + clicked
+        clamp_position
+        :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)
+        end.join("\n")
+      end
+
+      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?
       end
     end
   end

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

@@ -1,24 +1,28 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Markdown < Component
-        def initialize(content:, width: nil, theme: nil, syntax_highlighting: true)
-          super(theme: theme)
-          @content = content
-          @width = width
-          @syntax_highlighting = syntax_highlighting
-        end
+  module Components
+    # Markdown renders Markdown source as ANSI-styled terminal text. Parsing is delegated to
+    # `Charming::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
+        @width = width
+        @syntax_highlighting = syntax_highlighting
+      end
 
-        def render
-          Charming::Presentation::Markdown::Renderer.new(
-            content: @content,
-            width: @width,
-            theme: theme,
-            syntax_highlighting: @syntax_highlighting
-          ).render
-        end
+      # Renders the Markdown body to a styled, terminal-safe string.
+      def render
+        Charming::Markdown::Renderer.new(
+          content: @content,
+          width: @width,
+          theme: theme,
+          syntax_highlighting: @syntax_highlighting
+        ).render
       end
     end
   end

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

@@ -1,49 +1,61 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Modal < Component
-        def initialize(content:, title: nil, help: nil, width: 52, style: nil, theme: nil)
-          super(theme: theme)
-          @content = content
-          @title = title
-          @help = help
-          @width = width
-          @style = style
-        end
-
-        def render
-          box(column(*lines, gap: 1), style: modal_style)
-        end
-
-        private
-
-        attr_reader :content, :title, :help, :width
-
-        def lines
-          [title_line, help_line, render_content].compact
-        end
-
-        def title_line
-          text(title, style: theme.title.align(:center).width(title_width)) if title
-        end
-
-        def help_line
-          text(help, style: theme.muted) if help
-        end
-
-        def render_content
-          content.respond_to?(:render) ? render_component(content) : content.to_s
-        end
-
-        def modal_style
-          @style || theme.modal.width(width)
-        end
-
-        def title_width
-          [width - 8, 0].max
-        end
+  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
+        @title = title
+        @help = help
+        @width = width
+        @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
+
+      private
+
+      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
     end
   end

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

@@ -1,56 +1,67 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Progressbar < Component
-        attr_accessor :total, :current, :label, :complete, :incomplete, :bar_format
-
-        def initialize(total:, complete: "=", incomplete: " ", bar_format: :classic, label: nil)
-          super()
-          @total = [total.to_i, 0].max
-          @complete = complete.to_s
-          @incomplete = incomplete.to_s
-          @bar_format = bar_format.to_sym
-          @label = label
-          @current = 0
-        end
-
-        def tick(count = 1)
-          update(@current + count)
-          self
-        end
-
-        def update(value)
-          @current = value.to_i.clamp(0, @total)
-          self
-        end
-
-        def complete!
-          @current = @total
-          self
-        end
-
-        def render
-          width = [@total, 1].max
-          completed = completed_width(width)
-          incomplete = width - completed
-          incomplete -= 1 if @current.zero?
-          bar = (@complete * completed) + (@incomplete * incomplete)
-          result = "[" + bar + "]"
-
-          return result unless @label
-
-          "#{result} #{@label}"
-        end
-
-        private
-
-        def completed_width(width)
-          return 0 unless @total.positive?
-
-          ((width * @current) / @total.to_f).round
-        end
+  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
+        @complete = complete.to_s
+        @incomplete = incomplete.to_s
+        @bar_format = bar_format.to_sym
+        @label = label
+        @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)
+        incomplete = width - completed
+        incomplete -= 1 if @current.zero?
+        bar = (@complete * completed) + (@incomplete * incomplete)
+        result = "[" + bar + "]"
+
+        return result unless @label
+
+        "#{result} #{@label}"
+      end
+
+      private
+
+      # Returns the number of `complete` characters to draw, rounded to the nearest integer.
+      def completed_width(width)
+        return 0 unless @total.positive?
+
+        ((width * @current) / @total.to_f).round
       end
     end
   end