charming 0.2.1 → 0.2.3

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

@@ -39,8 +39,8 @@ module Charming
         result
       end
 
-      # Renders the modal as a bordered, padded string with the title and help lines stacked
-      # above the content.
+      # Renders the modal as a bordered, padded string with the title above the content
+      # and the help footer below it.
       def render
         box(column(*lines, gap: 1), style: modal_style)
       end
@@ -49,9 +49,9 @@ module Charming
 
       attr_reader :content, :title, :help, :width
 
-      # Returns the array of non-nil lines: title, help, content.
+      # Returns the array of non-nil lines: title, content, help footer.
       def lines
-        [title_line, help_line, body_content].compact
+        [title_line, body_content, help_line].compact
       end
 
       # The body: windowed through a Viewport when scrollable, otherwise rendered directly.

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?

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

@@ -72,12 +72,30 @@ module Charming
         rows[selected_index]
       end
 
+      # Sorts the body rows by *column* (a header label or 0-based index).
+      # Numeric-looking cells compare numerically; everything else as strings.
+      # The sorted column is marked ▲/▼ in the rendered header. Returns self.
+      def sort_by!(column, direction: :asc)
+        @sort_column = column_index(column)
+        @sort_direction = direction
+        sorted = @rows.sort_by { |row| sort_key(row) }
+        @rows = (direction == :desc) ? sorted.reverse : sorted
+        self
+      end
+
+      # Sorts by *column*, flipping the direction on repeated calls for the same
+      # column (ascending first). Returns self.
+      def toggle_sort(column)
+        flipping = @sort_column == column_index(column) && @sort_direction == :asc
+        sort_by!(column, direction: flipping ? :desc : :asc)
+      end
+
       # Renders the table to a string. Returns a placeholder when both header and rows are empty.
       def render
         return "(empty table)" if header.empty? && rows.empty?
 
         normalized = rows.map { |row| normalize_row(row) }
-        lines = TTY::Table.new(header: header, rows: normalized)
+        lines = TTY::Table.new(header: sort_marked_header, rows: normalized)
           .render(:unicode)
           .lines(chomp: true)
 
@@ -161,6 +179,29 @@ module Charming
         @selected_index = rows.length - 1
       end
 
+      # Resolves *column* (label or 0-based index) to a column index.
+      def column_index(column)
+        return column if column.is_a?(Integer) && column.between?(0, header.length - 1)
+
+        header.index(column.to_s) ||
+          raise(ArgumentError, "unknown column: #{column.inspect} (columns: #{header.join(", ")})")
+      end
+
+      # The comparable key for *row* at the active sort column: [0, number] for
+      # numeric-looking cells, [1, string] otherwise, so mixed columns still sort.
+      def sort_key(row)
+        cell = normalize_row(row)[@sort_column].to_s
+        cell.match?(/\A-?\d+(\.\d+)?\z/) ? [0, cell.to_f] : [1, cell]
+      end
+
+      # The header with the sorted column marked ▲ (ascending) or ▼ (descending).
+      def sort_marked_header
+        return header unless @sort_column
+
+        marker = (@sort_direction == :desc) ? "▼" : "▲"
+        header.each_with_index.map { |label, index| (index == @sort_column) ? "#{label} #{marker}" : label }
+      end
+
       # Clamps *value* to the valid row range, defaulting to 0 when the table is empty.
       def clamp_index(value)
         return 0 if rows.empty?

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

@@ -8,7 +8,7 @@ module Charming
     # for long buffers. Vertical movement preserves a "preferred column" so left/right
     # navigation feels stable.
     class TextArea < Component
-      # The current text value, cursor byte offset, top-visible row offset, and remembered
+      # The current text value, cursor character offset, top-visible row offset, and remembered
       # column for vertical navigation, respectively.
       attr_reader :value, :cursor, :offset, :preferred_column
 
@@ -212,7 +212,7 @@ module Charming
         [row, column]
       end
 
-      # Returns the byte offset where line *row* begins in the value.
+      # Returns the character offset where line *row* begins in the value.
       def line_start(row)
         lines.first(row).sum(&:length) + row
       end
@@ -259,8 +259,7 @@ module Charming
       def render_line(line)
         return line unless width
 
-        clipped = UI.visible_slice(line, 0, width)
-        clipped + (" " * [width - UI::Width.measure(clipped), 0].max)
+        UI::Width.pad_to(UI.visible_slice(line, 0, width), width)
       end
 
       # Adjusts the top-visible offset so the cursor row is in view. Scrolling is performed

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

@@ -25,7 +25,7 @@ module Charming
         delete: :delete_at_cursor
       }.freeze
 
-      # The current input string and the byte offset of the cursor within it.
+      # The current input string and the character offset of the cursor within it.
       attr_reader :value, :cursor
 
       # *value* is the initial text. *placeholder* is shown when the value is empty.
@@ -50,12 +50,17 @@ module Charming
         true
       end
 
-      # Handles key events. Inserts printable characters, recalls history on up/down
-      # (when enabled), otherwise dispatches via KEY_ACTIONS.
-      # Returns :handled when the event was consumed, nil otherwise.
+      # Handles key events. Inserts printable characters, submits on Enter
+      # (returning `[:submitted, value]` so a focused slot dispatches
+      # `<slot>_submitted(value)`), recalls history on up/down (when enabled),
+      # otherwise dispatches via KEY_ACTIONS.
+      # Returns :handled or `[:submitted, value]` when the event was consumed, nil otherwise.
       def handle_key(event)
         return :handled if character_event?(event) && insert(event.char)
-        return :handled if history_event(Charming.key_of(event))
+
+        key = Charming.key_of(event)
+        return [:submitted, value] if key == :enter
+        return :handled if history_event(key)
 
         super
       end
@@ -89,7 +94,7 @@ module Charming
         !char.match?(/[[:cntrl:]]/)
       end
 
-      # Inserts *char* at the cursor and advances the cursor by its byte length.
+      # Inserts *char* at the cursor and advances the cursor by its character length.
       def insert(char)
         @value = value[0...cursor] + char + value[cursor..]
         @cursor += char.length

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # TimeDisplay formats whole-second durations as clock strings: "mm:ss", or
+    # "h:mm:ss" once an hour is reached. Shared by Timer and Stopwatch.
+    module TimeDisplay
+      module_function
+
+      def clock(total_seconds)
+        seconds = [total_seconds.to_i, 0].max
+        hours, remainder = seconds.divmod(3600)
+        minutes, secs = remainder.divmod(60)
+        return format("%d:%02d:%02d", hours, minutes, secs) if hours.positive?
+
+        format("%02d:%02d", minutes, secs)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Timer is a countdown display. Drive it from a controller timer: call
+    # `tick` per interval and check `expired?` to act when time runs out.
+    class Timer < Component
+      attr_reader :duration, :remaining, :label
+
+      # *duration* is the countdown length in seconds. *label* is an optional
+      # suffix shown after the time.
+      def initialize(duration:, label: nil, theme: nil)
+        super(theme: theme)
+        @duration = [duration.to_i, 0].max
+        @remaining = @duration
+        @label = label
+      end
+
+      # Counts down by *seconds* (default 1), clamping at zero. Returns self.
+      def tick(seconds = 1)
+        @remaining = [@remaining - seconds, 0].max
+        self
+      end
+
+      # True once the countdown has reached zero.
+      def expired?
+        remaining.zero?
+      end
+
+      # Restores the full duration. Returns self.
+      def reset
+        @remaining = duration
+        self
+      end
+
+      # Renders the remaining time (with the label appended when present).
+      def render
+        clock = TimeDisplay.clock(remaining)
+        label ? "#{clock} #{label}" : clock
+      end
+    end
+  end
+end

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

@@ -3,9 +3,10 @@
 module Charming
   module Components
     # Toast is a small auto-dismissing notification panel, usually composited as an
-    # overlay anchored to a screen corner. Controllers manage its lifetime with the
-    # `show_toast` / `dismiss_toast` helpers (which pair it with a timer); the component
-    # itself just renders the styled box.
+    # overlay anchored to a screen corner. The component just renders the styled box;
+    # apps manage its lifetime themselves — typically a session-backed hash with an
+    # expiry deadline plus a controller timer that clears it (see the journal example's
+    # ApplicationController#show_toast / #expire_toast).
     #
     #   Toast.new(message: "Saved!", kind: :success)
     #

data/lib/charming/presentation/components/viewport/content_lines.rb

@@ -18,7 +18,7 @@ module Charming
         end
 
         def display_width
-          lines.map { |line| UI::Width.measure(line) }.max || 0
+          UI::Width.widest(lines)
         end
 
         private

data/lib/charming/presentation/components/viewport/line_window.rb

@@ -59,7 +59,7 @@ module Charming
         end
 
         def pad_line(line, target_width)
-          line + (" " * [target_width - UI::Width.measure(line), 0].max)
+          UI::Width.pad_to(line, target_width)
         end
 
         def ansi?(token)

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

@@ -25,7 +25,10 @@ module Charming
       # *content* may be a string, an array of lines, or any object responding to `render`.
       # *width* and *height* constrain the visible window; *offset* is the top-visible row
       # and *column* is the left-visible column. *wrap* enables soft-wrapping of long lines.
-      def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim)
+      # *follow* pins the viewport to the bottom of the content regardless of *offset*, so
+      # callers that rebuild each event stick to new content; pair with `at_bottom?` to
+      # decide whether to keep following after the user scrolls.
+      def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim, follow: false)
         super()
         @content = content
         @width = width
@@ -34,6 +37,7 @@ module Charming
         @wrap = wrap
         @keymap = keymap
         position.clamp(bounds)
+        position.move_to(max_offset, bounds) if follow
       end
 
       # Renders the visible window of content as a multi-line string.
@@ -51,6 +55,12 @@ module Charming
         @position.column
       end
 
+      # True when the last content row is visible. Callers persisting follow mode
+      # store this after key dispatch to decide whether the next build follows.
+      def at_bottom?
+        offset >= max_offset
+      end
+
       # Handles mouse events: scroll wheel adjusts the row offset, click moves the top
       # visible row to the clicked position. Returns :handled on success.
       def handle_mouse(event)

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

@@ -45,7 +45,7 @@ module Charming
       end
 
       def wrap(value, width:)
-        TextWrapper.new(width: width).wrap(value)
+        UI::TextWrapper.new(width: width).wrap(value)
       end
 
       def style_for(name, fallback:)

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

@@ -185,6 +185,7 @@ module Charming
 
       def self.builtin(name)
         key = name.to_s.tr("-", "_").to_sym
+        key = UI::Background.dark? ? :dark : :light if key == :auto
         raise ArgumentError, "unknown markdown style: #{name.inspect}" unless BUILT_INS.key?(key)
 
         from_hash(BUILT_INS.fetch(key))

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

@@ -30,8 +30,7 @@ module Charming
       end
 
       def table_cell(row, width, index)
-        value = row[index].to_s
-        " #{value}#{" " * [width - UI::Width.measure(value), 0].max} "
+        " #{UI::Width.pad_to(row[index].to_s, width)} "
       end
 
       def table_separator
@@ -40,7 +39,7 @@ module Charming
 
       def widths
         @widths ||= Array.new(column_count) do |index|
-          rows.map { |row| UI::Width.measure(row[index].to_s) }.max || 0
+          UI::Width.widest(rows.map { |row| row[index].to_s })
         end
       end