charming 0.2.0 → 0.2.1

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # FuzzyMatcher implements fzf-style subsequence matching with contiguity and
+    # word-boundary scoring. Used by CommandPalette (and available to any component
+    # that filters labels against typed input).
+    #
+    #   FuzzyMatcher.score("opl", "Open palette")  # => positive score
+    #   FuzzyMatcher.score("xyz", "Open palette")  # => nil (not a subsequence)
+    #   FuzzyMatcher.filter("op", commands, &:label)
+    module FuzzyMatcher
+      # Score bonuses: base per matched char, consecutive-run bonus, word-start bonus.
+      # The run bonus outweighs the word-start bonus so a literal substring match
+      # ("pal" in "Open palette") beats the same letters scattered across word starts.
+      CHAR_SCORE = 1
+      CONSECUTIVE_BONUS = 4
+      WORD_START_BONUS = 3
+
+      module_function
+
+      # Returns a relevance score when every character of *query* appears in order
+      # within *candidate* (case-insensitive), nil otherwise. Higher is better:
+      # contiguous runs and matches at word starts score above scattered matches.
+      # All alignments are considered (memoized), so "pal" finds the contiguous run
+      # in "Open palette" rather than the scattered greedy match.
+      def score(query, candidate)
+        q = query.to_s.downcase
+        c = candidate.to_s.downcase
+        return 0 if q.empty?
+
+        best_alignment(q, 0, c, 0, false, {})
+      end
+
+      # Finds the best-scoring alignment of q[qi..] within c[ci..]. *consecutive_at_ci*
+      # is true when the previous query char matched at ci - 1 (enabling the run bonus
+      # for a match exactly at ci). Returns nil when no alignment exists.
+      def best_alignment(q, qi, c, ci, consecutive_at_ci, memo)
+        return 0 if qi == q.length
+
+        key = [qi, ci, consecutive_at_ci]
+        return memo[key] if memo.key?(key)
+
+        best = nil
+        index = ci
+        while (index = c.index(q[qi], index))
+          points = CHAR_SCORE
+          points += CONSECUTIVE_BONUS if consecutive_at_ci && index == ci
+          points += WORD_START_BONUS if word_start?(c, index)
+          rest = best_alignment(q, qi + 1, c, index + 1, true, memo)
+          if rest
+            total = points + rest
+            best = total if best.nil? || total > best
+          end
+          index += 1
+        end
+
+        memo[key] = best
+      end
+
+      # Filters *candidates* to those matching *query*, ordered best-score first
+      # (original order breaks ties). The optional block extracts the searchable
+      # label from each candidate (defaults to to_s).
+      def filter(query, candidates, &label)
+        scored = candidates.each_with_index.filter_map do |candidate, index|
+          text = label ? yield(candidate) : candidate.to_s
+          candidate_score = score(query, text)
+          [candidate_score, index, candidate] if candidate_score
+        end
+
+        scored.sort_by { |candidate_score, index, _| [-candidate_score, index] }.map(&:last)
+      end
+
+      # True when the character at *index* starts a word: position 0 or preceded by
+      # a separator (space, underscore, hyphen, slash, dot, colon).
+      def word_start?(text, index)
+        return true if index.zero?
+
+        text[index - 1].match?(%r{[\s_\-/.:]})
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # HelpOverlay renders a controller's key bindings as a two-column cheat-sheet inside
+    # a Modal — the classic `?` help screen. Build it straight from a controller class:
+    #
+    #   HelpOverlay.for_controller(self.class, theme: theme)
+    #
+    # or with explicit entries:
+    #
+    #   HelpOverlay.new(bindings: {"q" => "Quit", "ctrl+p" => "Command palette"})
+    #
+    # Any key dismisses it (`handle_key` returns :cancelled).
+    class HelpOverlay < Component
+      DEFAULT_TITLE = "Keyboard Shortcuts"
+      DEFAULT_WIDTH = 44
+
+      # Builds an overlay from a controller class's `key_bindings` (key → action name).
+      # Action names are humanized into descriptions ("open_command_palette" → "Open command palette").
+      def self.for_controller(controller_class, title: DEFAULT_TITLE, theme: nil)
+        bindings = controller_class.key_bindings.transform_values do |action|
+          action.to_s.tr("_", " ").capitalize
+        end
+        new(bindings: bindings, title: title, theme: theme)
+      end
+
+      # *bindings* maps key names (symbols or strings) to description strings.
+      def initialize(bindings:, title: DEFAULT_TITLE, width: DEFAULT_WIDTH, theme: nil)
+        super(theme: theme)
+        @bindings = bindings
+        @title = title
+        @width = width
+      end
+
+      # Free-typed characters belong to this component while it is focused.
+      def captures_text?
+        true
+      end
+
+      # Any key dismisses the overlay.
+      def handle_key(_event)
+        :cancelled
+      end
+
+      # Renders the bindings table inside a titled modal.
+      def render
+        render_component(Modal.new(content: table, title: @title, width: @width, theme: theme))
+      end
+
+      private
+
+      # The two-column key/description table, keys right-padded to align.
+      def table
+        return theme.muted.render("No key bindings") if @bindings.empty?
+
+        key_width = @bindings.keys.map { |key| key.to_s.length }.max
+        @bindings.map do |key, description|
+          padded = key.to_s.ljust(key_width)
+          "#{theme.title.render(padded)}  #{description}"
+        end.join("\n")
+      end
+    end
+  end
+end

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/progressbar.rb

@@ -46,7 +46,6 @@ module Charming
         width = [@total, 1].max
         completed = completed_width(width)
         incomplete = width - completed
-        incomplete -= 1 if @current.zero?
         bar = (@complete * completed) + (@incomplete * incomplete)
         result = "[" + bar + "]"
 

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/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

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

@@ -16,7 +16,9 @@ module Charming
         up: :move_up,
         down: :move_down,
         home: :move_home,
-        end: :move_end
+        end: :move_end,
+        page_up: :page_up,
+        page_down: :page_down
       }.freeze
 
       # Number of terminal rows occupied by the table's top border and header line. Used by
@@ -29,12 +31,15 @@ module Charming
       # *header* is an array of column labels. *rows* is the array of body rows (each either a
       # String, an Array, or a Hash of column-value pairs). *selected_index* defaults to 0.
       # *keymap* selects the keybinding style (`:vim` enables h/j/k/l → left/down/up/right).
-      def initialize(header:, rows: [], selected_index: 0, keymap: :vim)
-        super()
+      # *height* optionally limits the visible body rows; the window auto-scrolls to keep
+      # the selection in view, and page up/down move by a full window.
+      def initialize(header:, rows: [], selected_index: 0, keymap: :vim, theme: nil, height: nil)
+        super(theme: theme)
         @header = Array(header).map(&:to_s)
         @rows = Array(rows)
         @selected_index = clamp_index(selected_index)
         @keymap = keymap
+        @height = height
       end
 
       # Handles key events. Returns `[:selected, row]` on Enter; otherwise delegates to the
@@ -48,16 +53,17 @@ module Charming
         end
       end
 
-      # Handles mouse events: a click within the body area selects the clicked row.
+      # Handles mouse events: a click within the body area selects the clicked row
+      # (relative to the visible window when a height is set).
       # Returns :handled on a successful click.
       def handle_mouse(event)
         return nil if rows.empty?
         return nil unless event.respond_to?(:click?) && event.click?
 
         clicked = event.y - HEADER_HEIGHT
-        return nil if clicked.negative? || clicked >= rows.length
+        return nil if clicked.negative? || clicked >= visible_row_count
 
-        @selected_index = clicked
+        @selected_index = viewport_start + clicked
         :handled
       end
 
@@ -95,7 +101,8 @@ module Charming
         kept + [merged]
       end
 
-      # Applies the selected-row highlight and trims unused body rows below the actual row count.
+      # Applies the selected-row highlight, windows the body to the configured height,
+      # and trims unused body rows below the actual row count.
       def compact_layout(lines)
         return lines.join("\n") if lines.length < 4
 
@@ -103,13 +110,37 @@ module Charming
         body = rest.first(rows.length)
         bottom = rest[rows.length]
 
-        highlighted = body.each_with_index.map do |line, index|
-          (index == selected_index) ? "\e[7m#{line}\e[m" : line
+        window = body[viewport_start, visible_row_count] || []
+        highlighted = window.each_with_index.map do |line, index|
+          ((viewport_start + index) == selected_index) ? theme.selected.render(line) : line
         end
 
         [top, header_line, *highlighted, bottom].compact.join("\n")
       end
 
+      # The top body row of the visible window (0 when no height is set), keeping the
+      # selection in view.
+      def viewport_start
+        return 0 unless @height
+
+        Layout.selected_window_start(selected_index: selected_index, item_count: rows.length, window_size: @height)
+      end
+
+      # The number of body rows shown at once.
+      def visible_row_count
+        @height ? [@height, rows.length].min : rows.length
+      end
+
+      # Moves the selection up by one window.
+      def page_up
+        @selected_index = [selected_index - visible_row_count, 0].max
+      end
+
+      # Moves the selection down by one window.
+      def page_down
+        @selected_index = [selected_index + visible_row_count, rows.length - 1].min
+      end
+
       # Moves the selection up one row.
       def move_up
         @selected_index -= 1 if selected_index.positive?