charming 0.2.0 → 0.2.2

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Chart plots a numeric *series* into a `width`×`height` box of character cells. `kind: :line`
+    # (default) draws a connected line on a {Charming::UI::BrailleCanvas} (subpixel resolution);
+    # `kind: :bar` draws vertical eighth-block bars. Pure text — works on every terminal — and
+    # composes with `row`/`column`/`box`. Pass an optional `style:` ({Charming::UI::Style}) to colour it.
+    class Chart < Component
+      # Vertical fill levels for bar mode, empty (0) to full (8 eighths).
+      VBARS = [" ", "▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"].freeze
+
+      # *series* is the numeric data. *width*/*height* size the chart in character cells. *kind* is
+      # `:line` or `:bar`. *style* optionally paints the result. *theme* is forwarded.
+      def initialize(series:, width:, height:, kind: :line, style: nil, theme: nil)
+        super(theme: theme)
+        @series = series
+        @width = width
+        @height = height
+        @kind = kind
+        @style = style
+      end
+
+      # Renders the chart (empty string for an empty series or a non-positive box).
+      def render
+        return "" if @series.empty? || @width < 1 || @height < 1
+
+        body = (@kind == :bar) ? bars : line_plot
+        @style ? @style.render(body) : body
+      end
+
+      private
+
+      # A connected line on a braille canvas sized to the cell box.
+      def line_plot
+        canvas = UI::BrailleCanvas.new(@width * 2, @height * 4)
+        points = scaled_points(@width * 2, @height * 4)
+        points.each { |x, y| canvas.set(x, y) }
+        points.each_cons(2) { |(x0, y0), (x1, y1)| canvas.line(x0, y0, x1, y1) }
+        canvas.to_s
+      end
+
+      # Maps the series to canvas pixels: x spread across the width, y inverted (0 at top) and scaled
+      # between the series' min and max.
+      def scaled_points(pixel_width, pixel_height)
+        min, max = @series.minmax
+        span = (max - min).to_f
+        span = 1.0 if span.zero?
+        last = @series.length - 1
+        @series.each_with_index.map do |value, index|
+          x = last.zero? ? 0 : (index * (pixel_width - 1) / last.to_f).round
+          y = ((1 - (value - min) / span) * (pixel_height - 1)).round
+          [x, y]
+        end
+      end
+
+      # Vertical eighth-block bars, one column per cell, sampled from the series and scaled from a
+      # baseline of min(0, series-min).
+      def bars
+        columns = sample(@series, @width)
+        base = [columns.min, 0].min
+        span = (columns.max - base).to_f
+        span = 1.0 if span.zero?
+        eighths = columns.map { |value| ((value - base) / span * @height * 8).round }
+        Array.new(@height) do |row|
+          from_bottom = @height - 1 - row
+          eighths.map { |total| VBARS[(total - from_bottom * 8).clamp(0, 8)] }.join
+        end.join("\n")
+      end
+
+      # Resamples *series* to exactly *count* values via nearest-neighbour (identity when sizes match).
+      def sample(series, count)
+        size = series.length
+        return series if size == count
+
+        Array.new(count) { |index| series[(index * size / count.to_f).floor.clamp(0, size - 1)] }
+      end
+    end
+  end
+end

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

@@ -43,6 +43,11 @@ module Charming
         }
       end
 
+      # Free-typed characters belong to this component while it is focused.
+      def captures_text?
+        true
+      end
+
       # Handles key events by routing them to the appropriate sub-component: Escape kills the
       # palette returning :cancelled; up/down/home/end keys go to the List selection handler
       # via handle_list_key; all other keys (including typed characters) are passed to the TextInput
@@ -104,14 +109,12 @@ module Charming
         List.new(items: filtered_commands, selected_index: selected_index, height: height, label: :label.to_proc, theme: theme)
       end
 
-      # Returns the full commands array when input value is empty; otherwise a subset whose labels match case-insensitively
-      # against the current TextInput value. Used to drive the fuzzy search behavior. Returns an Array of Command entries.
+      # Returns the full commands array when input value is empty; otherwise the commands
+      # fuzzy-matched against the typed value, best matches first (see FuzzyMatcher).
       def filtered_commands
         return commands if input.value.empty?
 
-        commands.select do |command|
-          command.label.downcase.include?(input.value.downcase)
-        end
+        FuzzyMatcher.filter(input.value, commands) { |command| command.label.to_s }
       end
     end
   end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # ErrorScreen renders an unhandled exception as a styled, centered panel instead of
+    # letting the backtrace crash into the raw terminal. Shows the exception class, message,
+    # the most relevant backtrace lines, and a dismiss hint. The Runtime displays it when a
+    # dispatched action raises and no `rescue_from` handler claimed the exception.
+    class ErrorScreen < Component
+      DEFAULT_WIDTH = 64
+      BACKTRACE_LINES = 6
+
+      # *error* is the rescued exception. *width* is the panel's total width. *root* is the
+      # app root used to shorten backtrace paths (defaults to the working directory).
+      def initialize(error:, width: DEFAULT_WIDTH, root: Dir.pwd, theme: nil)
+        super(theme: theme)
+        @error = error
+        @width = width
+        @root = root
+      end
+
+      # Renders the bordered error panel.
+      def render
+        box(column(*sections, gap: 1), style: panel_style)
+      end
+
+      private
+
+      attr_reader :error, :width, :root
+
+      # The panel sections: class name, message, backtrace, dismiss hint.
+      def sections
+        [
+          text(error.class.name, style: theme.warn.bold),
+          text(wrapped_message),
+          backtrace_section,
+          text("press any key to continue · q to quit", style: theme.muted)
+        ].compact
+      end
+
+      # The exception message, wrapped to the panel's inner width.
+      def wrapped_message
+        Charming::UI::TextWrapper.new(width: inner_width).wrap(error.message.to_s)
+      end
+
+      # The first few backtrace lines with the app root stripped, styled muted.
+      def backtrace_section
+        lines = (error.backtrace || []).first(BACKTRACE_LINES)
+        return nil if lines.empty?
+
+        body = lines.map { |line| shorten(line) }.join("\n")
+        text(body, style: theme.muted)
+      end
+
+      # Strips the app root prefix and clips each backtrace line to the inner width.
+      def shorten(line)
+        cleaned = line.delete_prefix("#{root}/")
+        UI.visible_slice(cleaned, 0, inner_width)
+      end
+
+      # The panel's content width inside border and padding.
+      def inner_width
+        [width - 6, 10].max
+      end
+
+      # The bordered panel style: warn-colored rounded border with padding.
+      def panel_style
+        style.border(:rounded, foreground: :red).padding(1, 2).width(width)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Filepicker is a directory browser built on List. Enter descends into the
+    # highlighted directory or returns `[:selected, absolute_path]` for a file;
+    # Backspace (or the "../" entry) goes up, never above the configured root.
+    # Dotfiles are hidden until `toggle_hidden`.
+    class Filepicker < Component
+      PARENT_ENTRY = "../"
+
+      # The directory currently being browsed.
+      attr_reader :current_dir
+
+      # *root* is the starting directory and the upper boundary for navigation.
+      # *show_hidden* includes dotfiles from the start. *height* windows the
+      # listing like List's height.
+      def initialize(root: Dir.pwd, show_hidden: false, height: nil, theme: nil, keymap: :vim)
+        super(theme: theme)
+        @root = File.expand_path(root)
+        @current_dir = @root
+        @show_hidden = show_hidden
+        @height = height
+        @keymap = keymap
+        rebuild_list
+      end
+
+      # The display entries for the current directory: an optional parent entry,
+      # then directories ("name/") before files, alphabetically.
+      def entries
+        list.items
+      end
+
+      # Handles navigation: Enter descends/selects, Backspace ascends, and all
+      # other keys delegate to the underlying List.
+      def handle_key(event)
+        case Charming.key_of(event)
+        when :enter then activate(list.selected_item)
+        when :backspace then ascend
+        else list.handle_key(event)
+        end
+      end
+
+      # Shows or hides dotfiles, refreshing the listing. Returns self.
+      def toggle_hidden
+        @show_hidden = !@show_hidden
+        rebuild_list
+        self
+      end
+
+      # Renders the current directory's listing via the underlying List.
+      def render
+        list.render
+      end
+
+      private
+
+      attr_reader :list
+
+      # Descends into directories, returns files as a selection.
+      def activate(entry)
+        return nil unless entry
+        return ascend if entry == PARENT_ENTRY
+        return descend(entry.delete_suffix("/")) if entry.end_with?("/")
+
+        [:selected, File.join(current_dir, entry)]
+      end
+
+      # Enters *name* under the current directory.
+      def descend(name)
+        @current_dir = File.join(current_dir, name)
+        rebuild_list
+        :handled
+      end
+
+      # Moves to the parent directory, unless already at the root.
+      def ascend
+        return nil if current_dir == @root
+
+        @current_dir = File.dirname(current_dir)
+        rebuild_list
+        :handled
+      end
+
+      # Builds a fresh List over the current directory's entries.
+      def rebuild_list
+        @list = List.new(items: directory_entries, height: @height, theme: theme, keymap: @keymap)
+      end
+
+      # Reads the current directory: parent entry (when below root), then
+      # directories before files, each group alphabetical, dotfiles filtered.
+      def directory_entries
+        names = Dir.children(current_dir).sort
+        names = names.reject { |name| name.start_with?(".") } unless @show_hidden
+        directories, files = names.partition { |name| File.directory?(File.join(current_dir, name)) }
+        parent = (current_dir == @root) ? [] : [PARENT_ENTRY]
+        parent + directories.map { |name| "#{name}/" } + files
+      end
+    end
+  end
+end

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

@@ -32,6 +32,11 @@ module Charming
           fields << Select.new(name, **field_options(options))
         end
 
+        # Appends a Multiselect field with the given *options* array.
+        def multiselect(name, **options)
+          fields << Multiselect.new(name, **field_options(options))
+        end
+
         # Appends a Confirm (boolean) field.
         def confirm(name, **options)
           fields << Confirm.new(name, **field_options(options))

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class Form
+      # Multiselect is a multiple-choice Form field backed by a MultiSelectList.
+      # Space toggles the highlighted option's checkbox, navigation keys move the
+      # highlight, and the checked set (in option order) becomes the field's value.
+      # Enter is left to the Form so it advances/submits like every other field.
+      class Multiselect < Field
+        # *options* is the array of selectable values. *selected_indices* pre-checks
+        # options. *max_selections* caps how many can be checked (nil = unlimited).
+        # *option_label* extracts the display string (default: `to_s`). All other
+        # options are forwarded to Field.
+        def initialize(name, options:, selected_indices: [], max_selections: nil, option_label: :to_s.to_proc, **field_options)
+          super(name, **field_options)
+          @options = options
+          @initial_indices = selected_indices
+          @max_selections = max_selections
+          @option_label = option_label
+        end
+
+        # Binds the field, then ensures the persisted checked set is applied.
+        def bind(state)
+          super
+          ensure_selection
+        end
+
+        # Forwards key events to the underlying MultiSelectList, syncing the checked
+        # set and highlight cursor back into the field state. Returns :handled when
+        # consumed; Enter (the list's submit) is left unconsumed for the Form.
+        def handle_key(event)
+          widget = list
+          result = widget.handle_key(event)
+          return nil if result.is_a?(Array)
+          return nil unless result == :handled
+
+          save_selection(widget)
+          :handled
+        end
+
+        private
+
+        attr_reader :options
+
+        # The default value is the pre-checked options, in option order.
+        def default_value
+          checked_options(normalized_initial_indices)
+        end
+
+        # Renders the field as "Label: choice, choice".
+        def render_control
+          "#{label}: #{display_value}"
+        end
+
+        # The checked options' labels joined for compact display.
+        def display_value
+          Array(value).map { |item| @option_label.call(item) }.join(", ")
+        end
+
+        # Builds a fresh MultiSelectList from the persisted checked set and cursor.
+        def list
+          MultiSelectList.new(
+            items: options,
+            selected_indices: field_state[:selected_indices],
+            selected_index: field_state[:cursor],
+            max_selections: @max_selections,
+            label: @option_label,
+            theme: theme
+          )
+        end
+
+        # Applies the persisted checked set (or the initial one) and highlight cursor.
+        def ensure_selection
+          checked = field_state[:selected_indices] || normalized_initial_indices
+          field_state[:selected_indices] = checked.sort
+          field_state[:cursor] ||= 0
+          state[:values][name] = checked_options(checked)
+        end
+
+        # Persists the widget's checked set and cursor, and the options as the value.
+        def save_selection(widget)
+          field_state[:selected_indices] = widget.selected_indices.sort
+          field_state[:cursor] = widget.selected_index
+          state[:values][name] = widget.selected_items
+        end
+
+        # The options at *indices*, in option order.
+        def checked_options(indices)
+          indices.sort.map { |index| options[index] }
+        end
+
+        # The initial indices, de-duplicated and clamped to the option range.
+        def normalized_initial_indices
+          @initial_indices.to_a.map(&:to_i).uniq.select { |index| index.between?(0, options.length - 1) }
+        end
+
+        # The per-field state hash for this field.
+        def field_state
+          state[:fields][name]
+        end
+      end
+    end
+  end
+end

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

@@ -7,6 +7,9 @@ module Charming
     # and bound to a per-form mutable state hash. Tab/Shift+Tab cycles focus through
     # focusable fields, Enter advances to the next field (or submits on the last), Escape
     # cancels, and Ctrl+S submits from any field.
+    #
+    # Exception: inside a Textarea field, Enter inserts a newline (it's a text editor) —
+    # leave it with Tab and submit with Ctrl+S, matching charm.sh's huh behavior.
     class Form < Component
       # The list of field objects and the mutable state hash the form is bound to.
       attr_reader :fields, :state
@@ -35,6 +38,12 @@ module Charming
         advance_or_submit if key == :enter
       end
 
+      # Forms accept free-typed text (their input/textarea fields do), so printable
+      # characters route here before global/content key bindings.
+      def captures_text?
+        true
+      end
+
       # Returns a hash of `{field_name => value}` for the current field values.
       def values
         state[:values]

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Image displays a {Charming::Image::Source} inline in the terminal, sized to *rows*×*cols*
+    # character cells. On a graphics-capable terminal (Phase 1: Ghostty/Kitty) it returns a block of
+    # Unicode placeholder cells and registers the image's one-time out-of-band transmission; on other
+    # terminals it returns *fallback* so layouts degrade gracefully.
+    #
+    # Like {Charming::Components::Audio}, the view itself is thin: the {Charming::Image::Source}
+    # (held in `session`) owns the bytes and transmit state. The placeholder block is a normal
+    # width-`cols` string that composes with `row`/`column`/`box` like any other view output.
+    class Image < Component
+      # *source* is the {Charming::Image::Source} to display. *rows*/*cols* size the image in
+      # character cells. *fallback* is shown when the terminal lacks graphics support. *theme* is
+      # forwarded to the view layer.
+      def initialize(source:, rows:, cols:, fallback: "", theme: nil)
+        super(theme: theme)
+        @source = source
+        @rows = rows
+        @cols = cols
+        @fallback = fallback
+      end
+
+      # Returns the placeholder block (registering the transmit once) on a graphics-capable terminal,
+      # otherwise the fallback string.
+      def render
+        return @fallback.to_s unless @source.supports_graphics?
+
+        unless @source.transmitted?
+          Charming::Escape.register(@source.transmit(rows: @rows, cols: @cols))
+          @source.mark_transmitted
+        end
+        @source.placement(rows: @rows, cols: @cols)
+      end
+    end
+  end
+end

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

@@ -19,20 +19,38 @@ module Charming
         end: :move_end
       }.freeze
 
-      # The item array and the currently selected index within it.
-      attr_reader :items, :selected_index
+      # The currently selected index (within the filtered view) and active filter query.
+      attr_reader :selected_index, :filter
 
       # *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)
+      # *filter* optionally narrows items by fuzzy-matching the label (see FuzzyMatcher);
+      # navigation, rendering, and selection all operate on the filtered view.
+      def initialize(items:, selected_index: 0, height: nil, label: nil, theme: nil, keymap: :vim, filter: nil)
         super(theme: theme)
-        @items = items
+        @source_items = items
         @selected_index = selected_index
         @height = height
         @label = label || :to_s.to_proc
         @keymap = keymap
+        @filter = filter
+        clamp_position
+      end
+
+      # The visible items: the source list narrowed by the active filter (best
+      # fuzzy match first), or the full source list when no filter is set.
+      def items
+        return @source_items if filter.nil? || filter.to_s.empty?
+
+        FuzzyMatcher.filter(filter, @source_items, &@label)
+      end
+
+      # Replaces the filter query (nil clears it) and reclamps the selection to
+      # the narrowed view.
+      def filter=(query)
+        @filter = query
         clamp_position
       end