charming 0.1.2 → 0.1.3

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

@@ -1,131 +1,129 @@
 # frozen_string_literal: true
 
 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
-
-        # 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
+  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,30 +1,28 @@
 # frozen_string_literal: true
 
 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
-          @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
 
-        # Renders the Markdown body to a styled, terminal-safe string.
-        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,63 +1,61 @@
 # frozen_string_literal: true
 
 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
-          @title = title
-          @help = help
-          @width = width
-          @style = style
-        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
+      # 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
+      private
 
-        attr_reader :content, :title, :help, :width
+      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 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 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 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 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 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
+      # 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,69 +1,67 @@
 # frozen_string_literal: true
 
 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
+  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
+      # *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
+      # 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
+      # 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
+      # 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 + "]"
+      # 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
+        return result unless @label
 
-          "#{result} #{@label}"
-        end
+        "#{result} #{@label}"
+      end
 
-        private
+      private
 
-        # Returns the number of `complete` characters to draw, rounded to the nearest integer.
-        def completed_width(width)
-          return 0 unless @total.positive?
+      # 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
+        ((width * @current) / @total.to_f).round
       end
     end
   end

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

@@ -1,48 +1,46 @@
 # frozen_string_literal: true
 
 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?
-
-          @frames = frames
-          @index = index
-          @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
-
-          "#{frame} #{label}"
-        end
-
-        private
-
-        # Returns the current frame string (with index modulo frame count to be safe).
-        def frame
-          frames.fetch(index % frames.length)
-        end
+  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?
+
+        @frames = frames
+        @index = index
+        @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
+
+        "#{frame} #{label}"
+      end
+
+      private
+
+      # Returns the current frame string (with index modulo frame count to be safe).
+      def frame
+        frames.fetch(index % frames.length)
       end
     end
   end