charming 0.2.1 → 0.2.2

data/lib/charming/internal/terminal/tty_backend.rb

@@ -68,6 +68,13 @@ module Charming
           nil
         end
 
+        # True when stdin has bytes ready to read right now — a genuine nonblocking check (0s
+        # wait), unlike read_event whose tty-reader nonblock path waits up to 0.1s. Lets the
+        # runtime drain buffered key auto-repeat and stop the instant the buffer empties.
+        def input_pending?
+          resized? || !@input.wait_readable(0).nil?
+        end
+
         # Emits the ANSI sequence enabling terminal focus reporting. Idempotent.
         def enable_focus_reporting
           return if @focus_reporting
@@ -100,6 +107,48 @@ module Charming
           @bracketed_paste = false
         end
 
+        # Returns the terminal to its normal state for a shell suspend (Ctrl+Z):
+        # reporting modes off, cursor visible, primary screen, cooked input.
+        def suspend
+          @mouse_was_enabled = @mouse_enabled
+          disable_mouse_tracking
+          disable_bracketed_paste
+          disable_focus_reporting
+          show_cursor
+          leave_alt_screen
+          @input.cooked! if @input.respond_to?(:cooked!)
+        end
+
+        # Re-enters the TUI after a resume (SIGCONT): raw/no-echo input, alt
+        # screen, hidden cursor, and the reporting modes that were active before
+        # the suspend. The caller is responsible for triggering a repaint.
+        def resume
+          @input.raw! if @input.respond_to?(:raw!)
+          @input.echo = false if @input.respond_to?(:echo=)
+          enter_alt_screen
+          hide_cursor
+          enable_mouse_tracking(motion: @mouse_motion || :drag) if @mouse_was_enabled
+          enable_bracketed_paste
+          enable_focus_reporting
+          clear
+        end
+
+        # The OSC 11 background-color query and the terminators a reply may end with.
+        BACKGROUND_QUERY = "\e]11;?\e\\"
+        OSC_TERMINATORS = ["\a", "\e\\"].freeze
+
+        # Queries the terminal's background color via OSC 11 and classifies the
+        # reply as :dark or :light. Returns nil when the input cannot be polled,
+        # the terminal stays silent past *timeout*, or the reply is unparseable.
+        # Call before the event loop starts — a reply arriving later would be
+        # read as keyboard input.
+        def query_background_color(timeout: 0.15)
+          return nil unless @input.respond_to?(:wait_readable)
+
+          write_control(BACKGROUND_QUERY)
+          UI::Background.parse_osc11(read_reply(timeout))
+        end
+
         # Keeps terminal input in raw/no-echo mode for the duration of a TUI run. Reading a
         # single keypress in raw mode is not enough: keys pressed while rendering or dispatching
         # events can otherwise be echoed into the alternate screen before the next read.
@@ -142,13 +191,15 @@ module Charming
 
         # Emits the ANSI sequences that enable terminal mouse reporting (press, motion, SGR).
         # Idempotent: skipped when mouse tracking is already enabled.
-        def enable_mouse_tracking
+        def enable_mouse_tracking(motion: :drag)
           return if @mouse_enabled
 
           write_control("\e[?1000h")
           write_control("\e[?1002h")
+          write_control("\e[?1003h") if motion == :all
           write_control("\e[?1006h")
           @mouse_enabled = true
+          @mouse_motion = motion
         end
 
         # Emits the ANSI sequences that disable terminal mouse reporting. Idempotent.
@@ -157,7 +208,7 @@ module Charming
 
           write_control("\e[?1000l")
           write_control("\e[?1002l")
-          write_control("\e[?1003l")
+          write_control("\e[?1003l") if @mouse_motion == :all
           write_control("\e[?1006l")
           @mouse_enabled = false
         end
@@ -187,6 +238,12 @@ module Charming
           end
         end
 
+        # Writes an out-of-band escape *sequence* (image transmission, clipboard, notification, title)
+        # raw — no cursor positioning, line-clearing, or auto-wrap handling that would corrupt it.
+        def write_escape(sequence)
+          write_control(sequence.payload)
+        end
+
         # Enters the alternate screen buffer.
         def enter_alt_screen
           write_control(ALT_SCREEN_ON)
@@ -222,6 +279,26 @@ module Charming
 
         private
 
+        # Accumulates an OSC reply from the input until a terminator arrives or
+        # *timeout* elapses. Returns whatever was read (possibly "").
+        def read_reply(timeout)
+          reply = +""
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          while (remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)) > 0
+            break unless @input.wait_readable(remaining)
+            break if append_reply_chunk(reply).nil?
+            break if OSC_TERMINATORS.any? { |terminator| reply.include?(terminator) }
+          end
+          reply
+        end
+
+        # Reads one available chunk into *reply*; nil at EOF or read error.
+        def append_reply_chunk(reply)
+          reply << @input.readpartial(64)
+        rescue IOError, SystemCallError
+          nil
+        end
+
         # True when the SIGWINCH flag has been set since the last read_event.
         def resized?
           @resized

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

@@ -154,7 +154,7 @@ module Charming
       end
 
       def widest_ellipsis_width
-        @widest_ellipsis_width ||= ELLIPSIS_FRAMES.map { |frame| UI::Width.measure(frame) }.max
+        @widest_ellipsis_width ||= UI::Width.widest(ELLIPSIS_FRAMES)
       end
 
       # Interpolates between gradient[0] and gradient[1] at the fractional +position+ (0.0 to 1.0).
@@ -162,24 +162,7 @@ module Charming
       def color_at(position)
         return gradient.first unless indicator_width > 1
 
-        blend(gradient.first, gradient.last, position / (indicator_width - 1).to_f)
-      end
-
-      # Blends two hex colors by interpolating their red/green/blue components at fractional +amount+.
-      # Accepts strings like "#ff0000" and produces a new "#rrggbb" string.
-      def blend(start_hex, end_hex, amount)
-        start_rgb = rgb(start_hex)
-        end_rgb = rgb(end_hex)
-        mixed = start_rgb.zip(end_rgb).map { |from, to| (from + ((to - from) * amount)).round }
-        "#%02x%02x%02x" % mixed
-      end
-
-      # Decomposes a hex color string ("#rrggbb") into an array of three integers [r, g, b].
-      def rgb(hex)
-        value = hex.to_s.delete_prefix("#")
-        raise ArgumentError, "gradient colors must be #rrggbb" unless value.match?(/\A[0-9a-fA-F]{6}\z/)
-
-        [value[0..1], value[2..3], value[4..5]].map { |part| part.to_i(16) }
+        UI::Gradient.blend(gradient.first, gradient.last, position / (indicator_width - 1).to_f)
       end
 
       # Advances the animation frame counter, wrapping around after +FRAME_COUNT+ (10) steps.

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

@@ -40,7 +40,7 @@ module Charming
 
       # The exception message, wrapped to the panel's inner width.
       def wrapped_message
-        Charming::Markdown::TextWrapper.new(width: inner_width).wrap(error.message.to_s)
+        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.

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

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,8 +48,7 @@ module Charming
       def render
         width = [@total, 1].max
         completed = completed_width(width)
-        incomplete = width - completed
-        bar = (@complete * completed) + (@incomplete * incomplete)
+        bar = filled_cells(completed, width) + (@incomplete * (width - completed))
         result = "[" + bar + "]"
 
         return result unless @label
@@ -54,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?