charming 0.2.0 → 0.2.2

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

@@ -3,14 +3,17 @@
 module Charming
   module Components
     # Markdown renders CommonMark/GFM source as ANSI-styled terminal text.
+    # *hyperlinks* (default false) emits OSC 8 escapes so links are clickable in
+    # modern terminals.
     class Markdown < Component
-      def initialize(content:, width: nil, theme: nil, syntax_highlighting: true, style: :dark, base_url: nil)
+      def initialize(content:, width: nil, theme: nil, syntax_highlighting: true, style: :dark, base_url: nil, hyperlinks: false)
         super(theme: theme)
         @content = content
         @width = width
         @syntax_highlighting = syntax_highlighting
         @style = style
         @base_url = base_url
+        @hyperlinks = hyperlinks
       end
 
       # Renders the Markdown body to a styled, terminal-safe string.
@@ -21,7 +24,8 @@ module Charming
           theme: theme,
           syntax_highlighting: @syntax_highlighting,
           style: @style,
-          base_url: @base_url
+          base_url: @base_url,
+          hyperlinks: @hyperlinks
         ).render
       end
     end

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

@@ -5,19 +5,40 @@ module Charming
     # 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.
+    #
+    # When *max_body_height* is given and the body is taller, the body is windowed through a
+    # Viewport: up/down (and page/home/end) keys scroll it via `handle_key`, and the current
+    # scroll position is exposed as `scroll_offset` so controllers can persist it.
     class Modal < Component
+      # The body's current scroll offset (only meaningful with max_body_height).
+      attr_reader :scroll_offset
+
       # *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)
+      # *max_body_height* caps the visible body rows (scrollable). *scroll_offset* restores a
+      # previous scroll position. *style* overrides the default `theme.modal` style.
+      def initialize(content:, title: nil, help: nil, width: 52, max_body_height: nil, scroll_offset: 0, style: nil, theme: nil)
         super(theme: theme)
         @content = content
         @title = title
         @help = help
         @width = width
+        @max_body_height = max_body_height
+        @scroll_offset = scroll_offset
         @style = style
       end
 
+      # Scrolls the body when it is taller than max_body_height. Returns :handled when the
+      # key moved the viewport, nil otherwise (so callers can route unconsumed keys).
+      def handle_key(event)
+        return nil unless scrollable?
+
+        viewport = body_viewport
+        result = viewport.handle_key(event)
+        @scroll_offset = viewport.offset
+        result
+      end
+
       # Renders the modal as a bordered, padded string with the title and help lines stacked
       # above the content.
       def render
@@ -30,7 +51,26 @@ module Charming
 
       # Returns the array of non-nil lines: title, help, content.
       def lines
-        [title_line, help_line, render_content].compact
+        [title_line, help_line, body_content].compact
+      end
+
+      # The body: windowed through a Viewport when scrollable, otherwise rendered directly.
+      def body_content
+        return render_content unless scrollable?
+
+        body_viewport.render
+      end
+
+      # True when a max body height is set and the content exceeds it.
+      def scrollable?
+        return false unless @max_body_height
+
+        render_content.lines.length > @max_body_height
+      end
+
+      # A Viewport over the rendered body at the current scroll offset.
+      def body_viewport
+        @body_viewport ||= Viewport.new(content: render_content, height: @max_body_height, offset: @scroll_offset)
       end
 
       # Returns the centered title line styled with the theme's title style, when a title was given.
@@ -43,9 +83,9 @@ module Charming
         text(help, style: theme.muted) if help
       end
 
-      # Returns the rendered content string, calling `render` on the body when applicable.
+      # Returns the rendered content string (memoized), calling `render` on the body when applicable.
       def render_content
-        content.respond_to?(:render) ? render_component(content) : content.to_s
+        @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.

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # MultiSelectList is a List variant where Space toggles per-item checkmarks and
+    # Enter submits the checked set. Renders `[x]` / `[ ]` prefixes.
+    #
+    # `handle_key` returns `[:submitted, [item, ...]]` on Enter, :handled for toggles
+    # and navigation, nil otherwise. *max_selections* optionally caps how many items
+    # can be checked at once.
+    class MultiSelectList < List
+      # The set of selected (checked) item indices.
+      attr_reader :selected_indices
+
+      # Same options as List, plus *selected_indices* (initially checked items) and
+      # *max_selections* (cap on simultaneous checks; nil = unlimited).
+      def initialize(items:, selected_indices: [], max_selections: nil, **options)
+        super(items: items, **options)
+        @selected_indices = selected_indices.to_a.map(&:to_i).uniq.select { |index| index.between?(0, items.length - 1) }
+        @max_selections = max_selections
+      end
+
+      # Space toggles the highlighted item, Enter submits the checked items.
+      def handle_key(event)
+        case Charming.key_of(event)
+        when :space then toggle_current
+        when :enter then [:submitted, selected_items]
+        else
+          # Bypass List#handle_key (its Enter means single-select); use its navigation.
+          keyboard_navigation(event)
+        end
+      end
+
+      # The checked items, in list order.
+      def selected_items
+        selected_indices.sort.map { |index| items[index] }
+      end
+
+      # Renders each visible item with a checkbox prefix; the highlighted row uses the
+      # selected style.
+      def render
+        visible_items.each_with_index.map do |item, index|
+          render_checkbox_item(item, viewport_start + index)
+        end.join("\n")
+      end
+
+      private
+
+      # Toggles the highlighted item's checkbox, respecting max_selections.
+      def toggle_current
+        index = selected_index
+        if selected_indices.include?(index)
+          selected_indices.delete(index)
+        else
+          return :handled if @max_selections && selected_indices.length >= @max_selections
+
+          selected_indices << index
+        end
+        :handled
+      end
+
+      # Navigation via the KeyboardHandler key actions (up/down/home/end and keymap aliases).
+      def keyboard_navigation(event)
+        key = Charming.key_of(event)
+        action = key_actions[key]
+        return nil unless action
+
+        send(action)
+        :handled
+      end
+
+      # One row: checkbox, then the labeled item; highlighted row in selected style.
+      def render_checkbox_item(item, index)
+        checkbox = selected_indices.include?(index) ? "[x]" : "[ ]"
+        rendered = "#{checkbox} #{label_for(item)}"
+        (index == selected_index) ? theme.selected.render(rendered) : rendered
+      end
+
+      # The display label for *item* via the List's label callable.
+      def label_for(item)
+        @label.call(item)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Paginator tracks a current page over a collection and renders a compact
+    # page indicator: bubbles-style dots ("○ ● ○") or arabic "2/3". Pair it with
+    # a List or Table by slicing items through `page_items`.
+    class Paginator < Component
+      ACTIVE_DOT = "●"
+      INACTIVE_DOT = "○"
+
+      attr_reader :page, :per_page, :total
+
+      # *total* is the collection size, *per_page* the page size, *page* the
+      # 0-based starting page, and *format* either :dots (default) or :arabic.
+      def initialize(total:, per_page:, page: 0, format: :dots, theme: nil)
+        super(theme: theme)
+        @total = [total.to_i, 0].max
+        @per_page = [per_page.to_i, 1].max
+        @format = format
+        @page = page.to_i.clamp(0, page_count - 1)
+      end
+
+      # The number of pages — at least 1, even for an empty collection.
+      def page_count
+        [(total.to_f / per_page).ceil, 1].max
+      end
+
+      # The slice of *items* belonging to the current page.
+      def page_items(items)
+        items[page * per_page, per_page] || []
+      end
+
+      # Advances one page, clamping at the last. Returns self.
+      def next_page
+        @page = [page + 1, page_count - 1].min
+        self
+      end
+
+      # Steps back one page, clamping at the first. Returns self.
+      def prev_page
+        @page = [page - 1, 0].max
+        self
+      end
+
+      # Renders the page indicator in the configured format.
+      def render
+        return "#{page + 1}/#{page_count}" if @format == :arabic
+
+        Array.new(page_count) { |index| (index == page) ? ACTIVE_DOT : INACTIVE_DOT }.join(" ")
+      end
+    end
+  end
+end

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

@@ -12,14 +12,17 @@ module Charming
 
       # *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)
+      # future format variants. *label* is an optional suffix shown after the bar. *gradient*
+      # is an optional ["#rrggbb", "#rrggbb"] pair that colors the filled region with a sweep
+      # across the full bar width.
+      def initialize(total:, complete: "=", incomplete: " ", bar_format: :classic, label: nil, gradient: nil)
         super()
         @total = [total.to_i, 0].max
         @complete = complete.to_s
         @incomplete = incomplete.to_s
         @bar_format = bar_format.to_sym
         @label = label
+        @gradient = gradient
         @current = 0
       end
 
@@ -45,9 +48,7 @@ module Charming
       def render
         width = [@total, 1].max
         completed = completed_width(width)
-        incomplete = width - completed
-        incomplete -= 1 if @current.zero?
-        bar = (@complete * completed) + (@incomplete * incomplete)
+        bar = filled_cells(completed, width) + (@incomplete * (width - completed))
         result = "[" + bar + "]"
 
         return result unless @label
@@ -55,8 +56,28 @@ module Charming
         "#{result} #{@label}"
       end
 
+      # The current completion as an integer percentage (0-100).
+      def percent
+        return 0 unless @total.positive?
+
+        ((@current * 100) / @total.to_f).round
+      end
+
       private
 
+      # The filled portion of the bar: plain characters, or — with a gradient —
+      # each cell colored along a sweep spanning the full bar width, so the
+      # visible colors stay stable as the bar fills.
+      def filled_cells(completed, width)
+        return @complete * completed unless @gradient
+
+        span = [width - 1, 1].max
+        Array.new(completed) do |index|
+          color = UI::Gradient.blend(@gradient.first, @gradient.last, index.to_f / span)
+          UI::Style.new(foreground: color).render(@complete)
+        end.join
+      end
+
       # 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/sparkline.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Sparkline renders a series of numbers as a compact one-line bar graph using the eighth-block
+    # glyphs `▁▂▃▄▅▆▇█` — one cell per value, scaled between the series' min and max. Pure text, so it
+    # works on every terminal. Pass an optional `style:` ({Charming::UI::Style}) to colour it.
+    class Sparkline < Component
+      # The eight bar heights, shortest to tallest.
+      BARS = %w[▁ ▂ ▃ ▄ ▅ ▆ ▇ █].freeze
+
+      # *values* is the numeric series. *style* optionally paints the result. *theme* is forwarded.
+      def initialize(values:, style: nil, theme: nil)
+        super(theme: theme)
+        @values = values
+        @style = style
+      end
+
+      # Renders one bar glyph per value (empty string for an empty series).
+      def render
+        return "" if @values.empty?
+
+        glyphs = @values.map { |value| BARS[level(value)] }.join
+        @style ? @style.render(glyphs) : glyphs
+      end
+
+      private
+
+      # The 0..7 bar index for *value*, scaled across the series range (flat series → lowest bar).
+      def level(value)
+        min, max = @values.minmax
+        return 0 if max == min
+
+        ((value - min).to_f / (max - min) * (BARS.length - 1)).round
+      end
+    end
+  end
+end

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

@@ -9,13 +9,32 @@ module Charming
       # The default frame set: a 4-frame ASCII spinner.
       DEFAULT_FRAMES = ["-", "\\", "|", "/"].freeze
 
+      # Named frame presets, mirroring the roster popularized by charm.sh's bubbles.
+      STYLES = {
+        line: DEFAULT_FRAMES,
+        dots: %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze,
+        mini_dot: %w[⠁ ⠂ ⠄ ⡀ ⢀ ⠠ ⠐ ⠈].freeze,
+        jump: %w[⢄ ⢂ ⢁ ⡁ ⡈ ⡐ ⡠].freeze,
+        pulse: %w[█ ▓ ▒ ░].freeze,
+        points: ["∙∙∙", "●∙∙", "∙●∙", "∙∙●"].freeze,
+        globe: %w[🌍 🌎 🌏].freeze,
+        moon: %w[🌑 🌒 🌓 🌔 🌕 🌖 🌗 🌘].freeze,
+        meter: %w[▱▱▱ ▰▱▱ ▰▰▱ ▰▰▰ ▰▰▱ ▰▱▱].freeze,
+        hamburger: %w[☱ ☲ ☴ ☲].freeze,
+        ellipsis: ["   ", ".  ", ".. ", "..."].freeze
+      }.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)
+      # *style* picks a named preset from STYLES (default :line). *frames* overrides the
+      # preset with any array of frame strings. *index* is the starting frame index.
+      # *label* is an optional suffix shown after the frame.
+      def initialize(style: :line, frames: nil, index: 0, label: nil)
         super()
+        frames ||= STYLES.fetch(style.to_sym) do
+          raise ArgumentError, "unknown spinner style: #{style.inspect} (available: #{STYLES.keys.join(", ")})"
+        end
         raise ArgumentError, "frames cannot be empty" if frames.empty?
 
         @frames = frames

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # StatusBar renders a single fixed-width row with left/center/right segments —
+    # the classic TUI bottom bar for mode indicators, hints, and app state.
+    #
+    #   StatusBar.new(width: screen.width, left: "NORMAL", right: "main ⎇")
+    #
+    # When *hints* is given (an array of [key, description] pairs), the center segment
+    # renders them as `key description` pairs — pass a controller's key bindings to get
+    # an automatic hint line.
+    class StatusBar < Component
+      # *width* is the total bar width. *left*/*center*/*right* are the segment contents.
+      # *hints* renders key-hint pairs in the center when no explicit center is given.
+      # *style* overrides the default bar background style.
+      def initialize(width:, left: "", center: "", right: "", hints: nil, style: nil, theme: nil)
+        super(theme: theme)
+        @width = width
+        @left = left.to_s
+        @center = center.to_s
+        @right = right.to_s
+        @hints = hints
+        @bar_style = style
+      end
+
+      # Renders the bar: left-aligned, centered, and right-aligned segments on one row,
+      # padded to the full width and wrapped in the bar style.
+      def render
+        resolved_style.render(compose_segments)
+      end
+
+      private
+
+      attr_reader :width, :left, :right
+
+      # The center content: the explicit center, or formatted hints when given.
+      def center
+        return @center unless @center.empty?
+        return "" unless @hints
+
+        @hints.map { |key, description| "#{key} #{description}" }.join("  ")
+      end
+
+      # Lays the three segments onto a single row of exactly *width* columns.
+      # Center is positioned at the true middle; left/right anchor the edges.
+      # Segments are clipped if they would collide.
+      def compose_segments
+        row = " " * width
+        row = place_segment(row, left, 0)
+        center_text = center
+        center_start = [(width - UI::Width.measure(center_text)) / 2, 0].max
+        row = place_segment(row, center_text, center_start)
+        right_start = [width - UI::Width.measure(right), 0].max
+        place_segment(row, right, right_start)
+      end
+
+      # Writes *text* into *row* starting at *column*, clipping to the row width.
+      def place_segment(row, text, column)
+        return row if text.empty?
+
+        visible = UI.visible_slice(text, 0, width - column)
+        prefix = UI.visible_slice(row, 0, column)
+        suffix_start = column + UI::Width.measure(visible)
+        suffix = UI.visible_slice(row, suffix_start, width - suffix_start)
+        "#{prefix}#{visible}#{suffix}"
+      end
+
+      # The user style or a muted reverse bar derived from the theme.
+      def resolved_style
+        @bar_style || theme.selected
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Stopwatch is a count-up display. Drive it from a controller timer: call
+    # `tick` per interval; elapsed time accumulates only while running.
+    class Stopwatch < Component
+      attr_reader :elapsed, :label
+
+      # *label* is an optional suffix shown after the time.
+      def initialize(label: nil, theme: nil)
+        super(theme: theme)
+        @elapsed = 0
+        @running = false
+        @label = label
+      end
+
+      # Starts accumulating time. Returns self.
+      def start
+        @running = true
+        self
+      end
+
+      # Pauses accumulation. Returns self.
+      def stop
+        @running = false
+        self
+      end
+
+      # True while the stopwatch is accumulating time.
+      def running?
+        @running
+      end
+
+      # Adds *seconds* (default 1) when running; a no-op otherwise. Returns self.
+      def tick(seconds = 1)
+        @elapsed += seconds.to_i if running?
+        self
+      end
+
+      # Stops and zeroes the elapsed time. Returns self.
+      def reset
+        @elapsed = 0
+        @running = false
+        self
+      end
+
+      # Renders the elapsed time (with the label appended when present).
+      def render
+        clock = TimeDisplay.clock(elapsed)
+        label ? "#{clock} #{label}" : clock
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # TabBar renders a horizontal list of tabs with one active tab, navigable with
+    # left/right (h/l in vim keymap) and selectable with Enter. Mouse clicks select the
+    # clicked tab.
+    #
+    #   TabBar.new(tabs: ["Files", "Search", "Git"], selected_index: 0)
+    #
+    # `handle_key` returns `[:selected, index]` on Enter, `:handled` for navigation keys,
+    # and nil otherwise.
+    class TabBar < Component
+      include KeyboardHandler
+
+      # Maps navigation keys to instance methods via KeyboardHandler.
+      KEY_ACTIONS = {
+        left: :move_left,
+        right: :move_right,
+        home: :move_home,
+        end: :move_end
+      }.freeze
+
+      # The tab labels and the index of the active tab.
+      attr_reader :tabs, :selected_index
+
+      # *tabs* is the array of tab labels. *selected_index* is the active tab (default 0).
+      # *separator* spaces the tabs apart.
+      def initialize(tabs:, selected_index: 0, separator: "  ", keymap: :vim, theme: nil)
+        super(theme: theme)
+        @tabs = Array(tabs).map(&:to_s)
+        @selected_index = @tabs.empty? ? 0 : selected_index.to_i.clamp(0, @tabs.length - 1)
+        @separator = separator
+        @keymap = keymap
+      end
+
+      # Returns `[:selected, index]` on Enter; navigation keys move the active tab.
+      def handle_key(event)
+        return nil if tabs.empty?
+        return [:selected, selected_index] if Charming.key_of(event) == :enter
+
+        super
+      end
+
+      # Selects the clicked tab. Returns :handled when a tab was hit, nil otherwise.
+      def handle_mouse(event)
+        return nil if tabs.empty?
+        return nil unless event.respond_to?(:click?) && event.click?
+
+        index = tab_index_at_column(event.x)
+        return nil unless index
+
+        @selected_index = index
+        :handled
+      end
+
+      # Renders the tabs on one row, the active tab in the selected style.
+      def render
+        tabs.each_with_index.map { |tab, index| render_tab(tab, index) }.join(@separator)
+      end
+
+      private
+
+      # Renders a single tab label, highlighting the active one.
+      def render_tab(tab, index)
+        label = " #{tab} "
+        (index == selected_index) ? theme.selected.render(label) : theme.muted.render(label)
+      end
+
+      # Maps a column offset to the tab whose rendered span covers it (nil between tabs).
+      def tab_index_at_column(column)
+        offset = 0
+        tabs.each_with_index do |tab, index|
+          tab_width = UI::Width.measure(" #{tab} ")
+          return index if column >= offset && column < offset + tab_width
+
+          offset += tab_width + UI::Width.measure(@separator)
+        end
+        nil
+      end
+
+      # Moves the active tab one position left.
+      def move_left
+        @selected_index -= 1 if selected_index.positive?
+      end
+
+      # Moves the active tab one position right.
+      def move_right
+        @selected_index += 1 if selected_index < tabs.length - 1
+      end
+
+      # Jumps to the first tab.
+      def move_home
+        @selected_index = 0
+      end
+
+      # Jumps to the last tab.
+      def move_end
+        @selected_index = tabs.length - 1
+      end
+    end
+  end
+end