charming 0.2.1 → 0.2.2

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # Gradient interpolates between two hex colors: blend a single point, build
+    # an evenly spaced ramp, or paint text with a per-character color sweep.
+    module Gradient
+      module_function
+
+      # Blends *start_hex* and *end_hex* ("#rrggbb") at fractional *amount*
+      # (0.0 → start, 1.0 → end), returning a "#rrggbb" string.
+      def blend(start_hex, end_hex, amount)
+        mixed = rgb(start_hex).zip(rgb(end_hex)).map do |from, to|
+          (from + ((to - from) * amount)).round
+        end
+        format("#%02x%02x%02x", *mixed)
+      end
+
+      # An evenly spaced ramp of *count* colors from *start_hex* to *end_hex*,
+      # endpoints included.
+      def steps(start_hex, end_hex, count)
+        return [blend(start_hex, end_hex, 0.0)] if count <= 1
+
+        Array.new(count) { |index| blend(start_hex, end_hex, index.to_f / (count - 1)) }
+      end
+
+      # Paints each grapheme cluster of plain-text *text* with a foreground color
+      # swept from *from* to *to* across its visible characters.
+      def colorize(text, from:, to:)
+        clusters = text.to_s.scan(Width::GRAPHEME)
+        span = [clusters.length - 1, 1].max
+
+        clusters.each_with_index.map do |cluster, index|
+          Style.new(foreground: blend(from, to, index.to_f / span)).render(cluster)
+        end.join
+      end
+
+      # Decomposes "#rrggbb" into [r, g, b] integers.
+      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) }
+      end
+    end
+  end
+end

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

@@ -18,6 +18,7 @@ module Charming
         @options = {
           attributes: [],
           padding: [0, 0, 0, 0],
+          margin: [0, 0, 0, 0],
           align: :left
         }.merge(options)
       end
@@ -49,11 +50,31 @@ module Charming
         with(padding: expand_box_values(values))
       end
 
+      # Returns a new Style with the margin set — blank space applied outside the border and
+      # untouched by the style's colors. Accepts the same CSS-style shorthand as `padding`.
+      def margin(*values)
+        with(margin: expand_box_values(values))
+      end
+
+      # Per-side setters: padding_top/right/bottom/left and margin_top/right/bottom/left,
+      # each returning a new Style with just that side changed.
+      %i[padding margin].each do |box|
+        %i[top right bottom left].each_with_index do |side, index|
+          define_method(:"#{box}_#{side}") do |value|
+            values = @options.fetch(box).dup
+            values[index] = value
+            with(box => values)
+          end
+        end
+      end
+
       # Returns a new Style with the border set. *style* is a border name (e.g., :normal,
-      # :rounded). *sides* optionally restricts the border to specific sides. *foreground*
-      # sets the border color.
-      def border(style = :normal, sides: nil, foreground: nil)
-        with(border: style, border_sides: sides, border_foreground: foreground)
+      # :rounded, :square, :hidden, :block) or a custom Border instance. *sides* optionally
+      # restricts the border to specific sides. *foreground* colors the border — a single
+      # color, or a per-side hash like `{top: :red, left: :green}`. *background* colors the
+      # border independently of the box background.
+      def border(style = :normal, sides: nil, foreground: nil, background: nil)
+        with(border: style, border_sides: sides, border_foreground: foreground, border_background: background)
       end
 
       # Returns a new Style that fixes the rendered width to *value* (in display columns).
@@ -66,19 +87,50 @@ module Charming
         with(height: value)
       end
 
+      # Returns a new Style that caps the rendered width to *value* display columns.
+      # Unlike `width`, content narrower than the cap is not padded out to it.
+      def max_width(value)
+        with(max_width: value)
+      end
+
+      # Returns a new Style that caps the rendered height to *value* rows. Unlike
+      # `height`, content shorter than the cap is not filled with blank rows.
+      def max_height(value)
+        with(max_height: value)
+      end
+
+      # Returns a new Style that word-wraps overflowing lines at the fixed width
+      # instead of clipping them.
+      def wrap
+        with(fit: :wrap)
+      end
+
+      # Returns a new Style that marks lines clipped at the fixed width with a
+      # trailing *ellipsis* instead of cutting them silently.
+      def truncate(ellipsis: Truncate::ELLIPSIS)
+        with(fit: :truncate, ellipsis: ellipsis)
+      end
+
       # Returns a new Style with horizontal alignment set (`:left`, `:right`, or `:center`).
       def align(value)
         with(align: value)
       end
 
+      # Returns a new Style with vertical alignment within a fixed height set
+      # (`:top`, `:middle`, or `:bottom`).
+      def align_vertical(value)
+        with(align_vertical: value)
+      end
+
       # Applies the configured style to *value* and returns the styled string. Steps:
-      # 1. wrap to `:width`, 2. align horizontally, 3. expand to `:height`, 4. apply padding,
-      # 5. paint border, 6. emit ANSI attribute/foreground/background escapes.
+      # 1. wrap to `:width`, 2. align horizontally and vertically, 3. expand to `:height`,
+      # 4. apply padding, 5. paint border, 6. emit ANSI attribute/foreground/background
+      # escapes, 7. surround with unstyled margin space.
       def render(value)
         lines = apply_dimensions(value.to_s.lines(chomp: true))
         lines = apply_padding(lines)
         lines = apply_border(lines)
-        apply_ansi(lines.join("\n"))
+        apply_margin(apply_ansi(lines.join("\n")))
       end
 
       private
@@ -91,40 +143,87 @@ module Charming
       # Wraps each line to the target width and applies horizontal alignment, then expands
       # to the target height.
       def apply_dimensions(lines)
+        lines = wrap_lines(lines)
         content_width = target_content_width(lines)
         dimensioned = lines.map { |line| align_line(fit_line(line, content_width), content_width) }
-        apply_height(dimensioned, content_width)
+        apply_max_height(apply_height(dimensioned, content_width))
+      end
+
+      # Word-wraps lines at the fixed width when the style is in wrap mode.
+      def wrap_lines(lines)
+        wrap_width = @options[:width]
+        return lines unless wrap_width && @options[:fit] == :wrap
+
+        wrapper = TextWrapper.new(width: wrap_width)
+        lines.flat_map { |line| wrapper.wrap(line).lines(chomp: true) }
       end
 
       # Returns the target content width: the explicit :width if set, otherwise the natural
-      # max display width of the lines.
+      # max display width of the lines, capped to :max_width when configured.
       def target_content_width(lines)
-        explicit_width = @options[:width]
-        natural_width = lines.map { |line| Width.measure(line) }.max || 0
-        explicit_width || natural_width
+        width = @options[:width] || Width.widest(lines)
+        max = @options[:max_width]
+        max ? [width, max].min : width
       end
 
-      # Clips *line* to *width* display columns, preserving ANSI styling where possible.
+      # Fits *line* into *width* display columns: clipped by default, or marked with an
+      # ellipsis in truncate mode. Preserves ANSI styling active at the cut.
       def fit_line(line, width)
         return line if Width.measure(line) <= width
+        return Truncate.tail(line, width, ellipsis: @options.fetch(:ellipsis, Truncate::ELLIPSIS)) if @options[:fit] == :truncate
 
         UI.visible_slice(line, 0, width)
       end
 
-      # Truncates or pads the lines array to *height* rows, filling with blank rows.
+      # Truncates or pads the lines array to *height* rows, distributing blank fill
+      # rows according to :align_vertical (:top, :middle, or :bottom).
       def apply_height(lines, width)
         height = @options[:height]
         return lines unless height
 
         visible = lines.first(height)
-        visible + Array.new([height - visible.length, 0].max) { " " * width }
+        distribute_rows(visible, height - visible.length, width)
+      end
+
+      # Places *missing* blank rows around *visible* per the vertical alignment.
+      def distribute_rows(visible, missing, width)
+        blank = ->(count) { Array.new([count, 0].max) { " " * width } }
+        case @options.fetch(:align_vertical, :top)
+        when :bottom
+          blank.call(missing) + visible
+        when :middle
+          top = missing / 2
+          blank.call(top) + visible + blank.call(missing - top)
+        else
+          visible + blank.call(missing)
+        end
+      end
+
+      # Surrounds the styled block with unstyled margin space: blank rows above and
+      # below, plain-space columns left and right. Applied after ANSI styling so the
+      # margin never carries the style's colors.
+      def apply_margin(styled)
+        top, right, bottom, left = @options.fetch(:margin)
+        return styled if [top, right, bottom, left].all?(&:zero?)
+
+        lines = styled.lines(chomp: true)
+        width = Width.widest(lines)
+        body = lines.map { |line| (" " * left) + Width.pad_to(line, width) + (" " * right) }
+        blank = " " * (left + width + right)
+        (Array.new(top, blank) + body + Array.new(bottom, blank)).join("\n")
+      end
+
+      # Caps the lines array to :max_height rows without filling missing rows.
+      def apply_max_height(lines)
+        max = @options[:max_height]
+        max ? lines.first(max) : lines
       end
 
       # Applies padding by prepending/appending blank rows (vertical) and indenting each
       # line (horizontal).
       def apply_padding(lines)
         top, right, bottom, left = @options.fetch(:padding)
-        inner_width = lines.map { |line| Width.measure(line) }.max || 0
+        inner_width = Width.widest(lines)
         empty = " " * (left + inner_width + right)
         padded = lines.map do |line|
           pad_line(line, inner_width, left, right)
@@ -143,7 +242,7 @@ module Charming
 
       # Pads a single line to *inner_width*, with *left* and *right* padding spaces.
       def pad_line(line, inner_width, left, right)
-        (" " * left) + line + (" " * (inner_width - Width.measure(line) + right))
+        (" " * left) + Width.pad_to(line, inner_width) + (" " * right)
       end
 
       # Builds a BorderPainter configured for the current border options.
@@ -152,13 +251,14 @@ module Charming
           border: Border.fetch(border_name),
           sides: @options[:border_sides],
           foreground: @options[:border_foreground],
-          background: @options[:background]
+          background: @options[:border_background] || @options[:background],
+          background_explicit: !@options[:border_background].nil?
         )
       end
 
       # Returns the natural display width of the longest line in *lines*.
       def content_width(lines)
-        lines.map { |line| Width.measure(line) }.max || 0
+        Width.widest(lines)
       end
 
       # Applies the active ANSI attribute/foreground/background codes to *value*.

data/lib/charming/presentation/{markdown → ui}/text_wrapper.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Charming
-  module Markdown
-    # TextWrapper wraps Markdown text blocks to a configured terminal width.
+  module UI
+    # TextWrapper greedily word-wraps text blocks to a display width.
     class TextWrapper
       def initialize(width:)
         @width = width
@@ -19,7 +19,7 @@ module Charming
       attr_reader :width
 
       def wrap_line(line)
-        return line if UI::Width.measure(line) <= width
+        return line if Width.measure(line) <= width
 
         wrap_words(line.split(/\s+/))
       end
@@ -31,7 +31,7 @@ module Charming
       def append_word(lines, word)
         current = lines.pop.to_s
         candidate = current.empty? ? word : "#{current} #{word}"
-        return lines.push(candidate) if current.empty? || UI::Width.measure(candidate) <= width
+        return lines.push(candidate) if current.empty? || Width.measure(candidate) <= width
 
         lines.push(current.rstrip, word)
       end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # Truncate cuts ANSI-styled text down to a display width, marking the cut
+    # with a trailing ellipsis. Styling active at the cut is preserved and
+    # terminated, and multi-column glyphs are never split (matching ANSISlicer).
+    module Truncate
+      ELLIPSIS = "…"
+
+      module_function
+
+      # Truncates each line of *text* to *width* display columns, appending
+      # *ellipsis* to lines that overflow. Lines that fit are returned unchanged.
+      def tail(text, width, ellipsis: ELLIPSIS)
+        text.to_s.lines(chomp: true).map { |line| tail_line(line, width, ellipsis) }.join("\n")
+      end
+
+      def tail_line(line, width, ellipsis)
+        return line if Width.measure(line) <= width
+
+        ellipsis_width = Width.measure(ellipsis)
+        return ANSISlicer.slice(line, 0, width) if ellipsis_width >= width
+
+        ANSISlicer.slice(line, 0, width - ellipsis_width) + ellipsis
+      end
+    end
+  end
+end

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

@@ -44,6 +44,17 @@ module Charming
       def strip_ansi(value)
         value.to_s.gsub(ANSI_PATTERN, "")
       end
+
+      # Pads *line* with trailing spaces to *width* display columns. Lines already at
+      # or beyond the target are returned unchanged.
+      def pad_to(line, width)
+        line + (" " * [width - measure(line), 0].max)
+      end
+
+      # The maximum display width across *lines*; 0 when there are none.
+      def widest(lines)
+        lines.map { |line| measure(line) }.max || 0
+      end
     end
   end
 end

data/lib/charming/presentation/ui.rb

@@ -13,22 +13,38 @@ module Charming
       Style.new
     end
 
+    # Builds a color that resolves to *light* or *dark* at render time based on
+    # the terminal background. Usable anywhere a color is accepted.
+    def adaptive(light:, dark:)
+      AdaptiveColor.new(light: light, dark: dark)
+    end
+
     # Horizontally concatenates *blocks* into a single multi-line string, padding each block's
     # rows to match the widest row. A *gap* argument (in spaces) can separate adjacent columns.
-    def join_horizontal(*blocks, gap: 0)
+    # *align* positions shorter blocks along the cross axis: `:top` (default), `:center`,
+    # `:bottom`, or a fraction between 0.0 and 1.0.
+    def join_horizontal(*blocks, gap: 0, align: :top)
       normalized = normalize_blocks(blocks)
+      height = block_height(normalized)
+      aligned = normalized.map { |lines| offset_rows(lines, height, align) }
       widths = block_widths(normalized)
       separator = " " * gap
 
-      Array.new(block_height(normalized)) do |index|
-        horizontal_line(normalized, widths, index).join(separator)
+      Array.new(height) do |index|
+        horizontal_line(aligned, widths, index).join(separator)
       end.join("\n")
     end
 
-    # Stacks *blocks* vertically separated by one or more blank lines. A *gap* of N inserts N
-    # extra newline characters between blocks (1 gap = 1 blank line, 2 gaps = 2 blank lines, etc.).
-    def join_vertical(*blocks, gap: 0)
-      blocks.join("\n" * (gap + 1))
+    # Stacks *blocks* vertically separated by one or more blank lines, padding narrower
+    # blocks' lines to the widest block. A *gap* of N inserts N extra newline characters
+    # between blocks. *align* positions narrower lines along the cross axis: `:left`
+    # (default), `:center`, `:right`, or a fraction between 0.0 and 1.0.
+    def join_vertical(*blocks, gap: 0, align: :left)
+      normalized = normalize_blocks(blocks)
+      width = block_widths(normalized).max || 0
+
+      normalized.map { |lines| lines.map { |line| align_to(line, width, align) }.join("\n") }
+        .join("\n" * (gap + 1))
     end
 
     # Places *block* onto a blank canvas of *width* × *height* at an offset determined by *top* (row)
@@ -63,13 +79,13 @@ module Charming
 
     # Measures the displayed (visual) width of each normalised block, returning an array of integer widths.
     def block_widths(blocks)
-      blocks.map { |lines| lines.map { |line| Width.measure(line) }.max || 0 }
+      blocks.map { |lines| Width.widest(lines) }
     end
 
     # Returns the maximum visual character width across all *lines*, accounting for multi-column characters
     # (e.g., full-width CJK glyphs) and invisible ANSI escape sequences.
     def block_width(lines)
-      lines.map { |line| Width.measure(line) }.max || 0
+      Width.widest(lines)
     end
 
     # Returns the height in rows of each normalised block, taking the maximum across all blocks.
@@ -81,9 +97,34 @@ module Charming
     # every segment to its corresponding *width* in spaces. Returns the assembled array of padded segments.
     def horizontal_line(blocks, widths, index)
       blocks.each_with_index.map do |lines, block_index|
-        line = lines[index] || ""
-        line + (" " * (widths[block_index] - Width.measure(line)))
+        Width.pad_to(lines[index] || "", widths[block_index])
       end
     end
+
+    # Prepends blank rows to *lines* so the block sits at the cross-axis position
+    # given by *align* within *height* total rows.
+    def offset_rows(lines, height, align)
+      Array.new(cross_offset(align, height - lines.length), "") + lines
+    end
+
+    # Pads *line* to *width*, splitting the slack per the cross-axis *align* position.
+    def align_to(line, width, align)
+      slack = width - Width.measure(line)
+      return line if slack <= 0
+
+      leading = cross_offset(align, slack)
+      (" " * leading) + line + (" " * (slack - leading))
+    end
+
+    # Resolves an alignment (`:top`/`:left` → 0.0, `:center` → 0.5, `:bottom`/`:right` → 1.0,
+    # or a fraction) into a whole-cell offset within *slack* spare cells.
+    CROSS_POSITIONS = {top: 0.0, left: 0.0, center: 0.5, middle: 0.5, bottom: 1.0, right: 1.0}.freeze
+
+    def cross_offset(align, slack)
+      return 0 if slack <= 0
+
+      position = CROSS_POSITIONS.fetch(align, align)
+      (slack * position.to_f).round.clamp(0, slack)
+    end
   end
 end

data/lib/charming/presentation/view.rb

@@ -57,14 +57,16 @@ module Charming
       apply_style(content, style)
     end
 
-    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports a `gap:` parameter.
-    def row(*items, gap: 0)
-      UI.join_horizontal(*items, gap: gap)
+    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports `gap:`
+    # spacing and cross-axis `align:` (`:top`/`:center`/`:bottom` or a 0.0–1.0 fraction).
+    def row(*items, gap: 0, align: :top)
+      UI.join_horizontal(*items, gap: gap, align: align)
     end
 
-    # Stacks items vertically using the UI rendering engine. Supports a `gap:` parameter for spacing.
-    def column(*items, gap: 0)
-      UI.join_vertical(*items, gap: gap)
+    # Stacks items vertically using the UI rendering engine. Supports `gap:` spacing and
+    # cross-axis `align:` (`:left`/`:center`/`:right` or a 0.0–1.0 fraction).
+    def column(*items, gap: 0, align: :left)
+      UI.join_vertical(*items, gap: gap, align: align)
     end
 
     # Renders a component (e.g., a ProgressBar, Spinner, Modal) and returns its string output.

data/lib/charming/response.rb

@@ -4,20 +4,25 @@ module Charming
   # Response encapsulates a controller's dispatch outcome — one of render text, navigate to another route, or quit.
   # Rails-style factories (`render`, `navigate`, `quit`) serve as the public API and map to :kind values
   # that the Runtime interprets at the end of each event loop iteration.
-  Response = Data.define(:kind, :body, :path) do
-    # Factory constructing a Render response for displaying *body* text on the current screen.
-    def self.render(body)
-      new(kind: :render, body: body, path: nil)
+  #
+  # *escapes* carries any out-of-band terminal sequences (image transmissions, clipboard writes,
+  # notifications, window-title changes) gathered during the dispatch. The Runtime flushes them straight
+  # to the backend, bypassing the line-based frame pipeline. It is empty for ordinary responses.
+  Response = Data.define(:kind, :body, :path, :escapes) do
+    # Factory constructing a Render response for displaying *body* text on the current screen. *escapes*
+    # is the list of out-of-band sequences gathered during the dispatch (defaults to none).
+    def self.render(body, escapes: [])
+      new(kind: :render, body: body, path: nil, escapes: escapes)
     end
 
     # Factory constructing a NavigateResponse routing to the named *path* (string).
     def self.navigate(path)
-      new(kind: :navigate, body: "", path: path)
+      new(kind: :navigate, body: "", path: path, escapes: [])
     end
 
     # Factory constructing a QuitResponse signalling termination of the top-level event loop.
     def self.quit
-      new(kind: :quit, body: "", path: nil)
+      new(kind: :quit, body: "", path: nil, escapes: [])
     end
 
     # Returns `true` when this response is navigating to another screen or route.