charming 0.2.1 → 0.2.2

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.to_i if running?
+        self
+      end
+
+      # Stops and zeroes the elapsed time. Returns self.
+      def reset
+        @elapsed = 0
+        @running = false
+        self
+      end
+
+      # Renders the elapsed time (with the label appended when present).
+      def render
+        clock = TimeDisplay.clock(elapsed)
+        label ? "#{clock} #{label}" : clock
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/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

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

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

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.to_i, 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/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/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
 

data/lib/charming/presentation/ui/adaptive_color.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # AdaptiveColor is a color value that resolves to its light or dark variant
+    # at render time, based on the detected terminal background. Build one with
+    # `UI.adaptive(light:, dark:)` and use it anywhere a color is accepted.
+    class AdaptiveColor
+      def initialize(light:, dark:)
+        @light = light
+        @dark = dark
+      end
+
+      # The variant readable on the current terminal background.
+      def resolve
+        Background.dark? ? @dark : @light
+      end
+    end
+  end
+end

data/lib/charming/presentation/ui/ansi_codes.rb

@@ -57,8 +57,10 @@ module Charming
       end
 
       # Resolves *color* to SGR codes, downconverting to the terminal's capability
-      # (see UI::ColorSupport): truecolor → 256 → 16 → none.
+      # (see UI::ColorSupport): truecolor → 256 → 16 → none. Adaptive colors
+      # resolve against the terminal background first.
       def color_codes(color, foreground:)
+        color = color.resolve if color.respond_to?(:resolve)
         return [] unless color
         return [] if ColorSupport.level == :none
         return indexed_color_code(color, foreground: foreground) if color.is_a?(Integer)
@@ -82,7 +84,8 @@ module Charming
 
       def truecolor_codes(color, foreground:)
         hex = color.to_s.delete_prefix("#")
-        raise ArgumentError, "truecolor must be #rrggbb" unless hex.match?(/\A[0-9a-fA-F]{6}\z/)
+        hex = hex.chars.map { |digit| digit * 2 }.join if hex.match?(/\A[0-9a-fA-F]{3}\z/)
+        raise ArgumentError, "truecolor must be #rgb or #rrggbb" unless hex.match?(/\A[0-9a-fA-F]{6}\z/)
         return [foreground ? 38 : 48, 5, ColorSupport.hex_to_256(hex)] if ColorSupport.level == :color256
         return basic_color_code(ColorSupport.hex_to_16(hex), foreground: foreground) if ColorSupport.level == :color16
 

data/lib/charming/presentation/ui/background.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # Background tracks whether the terminal has a dark or light background so
+    # adaptive colors and the markdown :auto style can pick the readable variant.
+    #
+    # The runtime feeds a definitive answer from an OSC 11 query when the
+    # terminal replies to one (see TTYBackend#query_background_color); otherwise
+    # detection falls back to the COLORFGBG convention and finally assumes dark —
+    # the overwhelmingly common terminal default. `Background.assume = :light`
+    # overrides everything (useful in tests and for user preference).
+    module Background
+      MODES = %i[dark light].freeze
+
+      # ITU-R BT.601 luma threshold on 8-bit channels: below this is "dark".
+      LUMA_THRESHOLD = 128
+
+      module_function
+
+      # True when the terminal background is dark (the assumed mode, or detection).
+      def dark?
+        (@assumed || detect(ENV)) == :dark
+      end
+
+      # Overrides detection with :dark or :light; nil returns to auto-detection.
+      def assume=(value)
+        raise ArgumentError, "unknown background: #{value.inspect}" if value && !MODES.include?(value)
+
+        @assumed = value
+      end
+
+      # Detects the background from an environment hash via the COLORFGBG
+      # convention ("<fg>;<bg>", where bg 7 or 15 means a light background).
+      # Defaults to :dark when the environment says nothing.
+      def detect(env)
+        bg_index = env["COLORFGBG"].to_s.split(";").last
+        %w[7 15].include?(bg_index) ? :light : :dark
+      end
+
+      # Classifies an 8-bit RGB triple as :dark or :light by luma.
+      def classify(red, green, blue)
+        luma = (0.299 * red) + (0.587 * green) + (0.114 * blue)
+        (luma < LUMA_THRESHOLD) ? :dark : :light
+      end
+
+      # Parses an OSC 11 reply ("\e]11;rgb:RRRR/GGGG/BBBB" + BEL or ST) and
+      # classifies the reported color. Returns nil for anything unparseable.
+      def parse_osc11(reply)
+        match = reply.to_s.match(%r{\e\]11;rgb:(\h{2,4})/(\h{2,4})/(\h{2,4})})
+        return unless match
+
+        red, green, blue = match.captures.map { |channel| channel[0, 2].to_i(16) }
+        classify(red, green, blue)
+      end
+    end
+  end
+end

data/lib/charming/presentation/ui/border.rb

@@ -10,7 +10,11 @@ module Charming
         @horizontal, @vertical = edges
       end
 
+      # Resolves *name* to a Border: a Border instance passes through (custom
+      # borders), anything else is looked up in the built-in STYLES.
       def self.fetch(name)
+        return name if name.is_a?(Border)
+
         STYLES.fetch(name.to_sym)
       end
     end
@@ -27,7 +31,16 @@ module Charming
       ),
       double: Border.new(
         corners: ["╔", "╗", "╚", "╝"], edges: ["═", "║"]
+      ),
+      square: Border.new(
+        corners: ["┌", "┐", "└", "┘"], edges: ["─", "│"]
+      ),
+      hidden: Border.new(
+        corners: [" ", " ", " ", " "], edges: [" ", " "]
+      ),
+      block: Border.new(
+        corners: ["█", "█", "█", "█"], edges: ["█", "█"]
       )
-    }.freeze
+    }.tap { |styles| styles[:ascii] = styles[:normal] }.freeze
   end
 end

data/lib/charming/presentation/ui/border_painter.rb

@@ -2,14 +2,21 @@
 
 module Charming
   module UI
+    # BorderPainter draws a Border's glyphs around content lines, optionally
+    # coloring the border. *foreground* is a single color or a per-side hash
+    # (`{top:, right:, bottom:, left:}`); corners take the top/bottom row's
+    # color. *background* colors border cells; when it merely inherits the box
+    # background (background_explicit: false) it only paints alongside a
+    # foreground, preserving unstyled borders on unstyled boxes.
     class BorderPainter
       DEFAULT_SIDES = %i[top right bottom left].freeze
 
-      def initialize(border:, sides: nil, foreground: nil, background: nil)
+      def initialize(border:, sides: nil, foreground: nil, background: nil, background_explicit: false)
         @border = border
         @sides = Array(sides || DEFAULT_SIDES).map(&:to_sym)
         @foreground = foreground
         @background = background
+        @background_explicit = background_explicit
       end
 
       def paint(lines, inner_width)
@@ -22,34 +29,39 @@ module Charming
       private
 
       def border_line(line, width)
-        left = @sides.include?(:left) ? render_border(@border.vertical) : ""
-        right = @sides.include?(:right) ? render_border(@border.vertical) : ""
+        left = @sides.include?(:left) ? render_border(@border.vertical, :left) : ""
+        right = @sides.include?(:right) ? render_border(@border.vertical, :right) : ""
 
-        "#{left}#{line}#{" " * (width - Width.measure(line))}#{right}"
+        "#{left}#{Width.pad_to(line, width)}#{right}"
       end
 
       def top_border(horizontal)
         return unless @sides.include?(:top)
-        return render_border(horizontal) unless full_horizontal?
+        return render_border(horizontal, :top) unless full_horizontal?
 
-        render_border("#{@border.top_left}#{horizontal}#{@border.top_right}")
+        render_border("#{@border.top_left}#{horizontal}#{@border.top_right}", :top)
       end
 
       def bottom_border(horizontal)
         return unless @sides.include?(:bottom)
-        return render_border(horizontal) unless full_horizontal?
+        return render_border(horizontal, :bottom) unless full_horizontal?
 
-        render_border("#{@border.bottom_left}#{horizontal}#{@border.bottom_right}")
+        render_border("#{@border.bottom_left}#{horizontal}#{@border.bottom_right}", :bottom)
       end
 
       def full_horizontal?
         @sides.include?(:left) && @sides.include?(:right)
       end
 
-      def render_border(value)
-        return value unless @foreground
+      def render_border(value, side)
+        foreground = side_foreground(side)
+        return value unless foreground || @background_explicit
 
-        Style.new(foreground: @foreground, background: @background).render(value)
+        Style.new(foreground: foreground, background: @background).render(value)
+      end
+
+      def side_foreground(side)
+        @foreground.is_a?(Hash) ? @foreground[side] : @foreground
       end
     end
   end

data/lib/charming/presentation/ui/braille_canvas.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # BrailleCanvas is a monochrome subpixel drawing surface backed by Unicode braille glyphs
+    # (U+2800–U+28FF). Each character cell packs a 2×4 grid of dots, so the canvas addresses
+    # `width`×`height` *pixels* while rendering to `cols`×`rows` *cells* — 8× the vertical and 2× the
+    # horizontal resolution of plain text. It's pure text (works on every terminal) and composes via
+    # `row`/`column`/`Canvas` like any other block. Used by {Charming::Components::Chart}.
+    class BrailleCanvas
+      # The first braille code point; OR-ing dot bits onto it yields the glyph for a cell.
+      BASE = 0x2800
+
+      # Dot bit for each (x%2, y%4) position within a cell, indexed `DOTS[y % 4][x % 2]`.
+      DOTS = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, 0x80]].freeze
+
+      # *width* and *height* are the drawable area in pixels (dots).
+      def initialize(width, height)
+        @width = width
+        @height = height
+        @cols = (width + 1) / 2
+        @rows = (height + 3) / 4
+        @cells = Array.new(@rows) { Array.new(@cols, 0) }
+      end
+
+      attr_reader :width, :height, :cols, :rows
+
+      # Turns the dot at pixel (*x*, *y*) on (or off when `on: false`). Out-of-range points are
+      # ignored. Returns self for chaining.
+      def set(x, y, on: true)
+        return self unless x.between?(0, @width - 1) && y.between?(0, @height - 1)
+
+        bit = DOTS[y % 4][x % 2]
+        if on
+          @cells[y / 4][x / 2] |= bit
+        else
+          @cells[y / 4][x / 2] &= ~bit
+        end
+        self
+      end
+
+      # Turns the dot at pixel (*x*, *y*) off. Returns self.
+      def unset(x, y)
+        set(x, y, on: false)
+      end
+
+      # Draws a straight line between (*x0*, *y0*) and (*x1*, *y1*) with Bresenham's algorithm.
+      # Returns self.
+      def line(x0, y0, x1, y1)
+        dx = (x1 - x0).abs
+        dy = -(y1 - y0).abs
+        sx = (x0 < x1) ? 1 : -1
+        sy = (y0 < y1) ? 1 : -1
+        err = dx + dy
+        x = x0
+        y = y0
+        loop do
+          set(x, y)
+          break if x == x1 && y == y1
+
+          e2 = 2 * err
+          if e2 >= dy
+            err += dy
+            x += sx
+          end
+          if e2 <= dx
+            err += dx
+            y += sy
+          end
+        end
+        self
+      end
+
+      # Renders the canvas as `rows` lines of `cols` braille glyphs.
+      def to_s
+        @cells.map { |row| row.map { |bits| (BASE + bits).chr(Encoding::UTF_8) }.join }.join("\n")
+      end
+    end
+  end
+end

data/lib/charming/presentation/ui/canvas.rb

@@ -44,6 +44,7 @@ module Charming
 
       def self.offset(value, available, size)
         return [(available - size) / 2, 0].max if value == :center
+        return [((available - size) * value).round, 0].max if value.is_a?(Float)
 
         value
       end