charming 0.2.1 → 0.2.3

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

@@ -5,21 +5,23 @@ module Charming
     module Terminal
       # MouseParser parses raw terminal escape sequences into MouseEvent objects.
       # Supports both modern SGR sequences (the most common, used by current terminals)
-      # and the older 3-byte legacy sequences. The public API is class methods; no
-      # instance state is required.
+      # and the older 3-byte legacy sequences. Both encodings pack modifiers and motion
+      # into the button code: bit 2 shift, bit 3 alt/meta, bit 4 ctrl, bit 5 motion.
+      # SGR signals release with a final "m" instead of "M". The public API is class
+      # methods; no instance state is required.
       class MouseParser
-        # Matches an SGR-encoded mouse sequence: "\e[<button;col;row[mode]M"
-        SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)([HmMhCc]?)(M|m)/
+        # Matches an SGR-encoded mouse sequence: "\e[<button;col;row" + "M" (press) or "m" (release).
+        SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)(M|m)/
 
         # Matches the legacy 3-byte mouse sequence: "\e[M" followed by 3 bytes.
         LEGACY_PATTERN = /\e\[M(.{3})/
 
-        # Maps raw button codes to semantic symbols used by MouseEvent#button_name.
-        BUTTON_MAP = {
-          0 => :left, 1 => :middle, 2 => :right, 3 => :release,
-          64 => :scroll_up, 65 => :scroll_down,
-          66 => :scroll_up, 67 => :scroll_down
-        }.freeze
+        # Button-code bits for modifier keys and motion (shared by SGR and legacy).
+        SHIFT_BIT = 4
+        ALT_BIT = 8
+        CTRL_BIT = 16
+        MOTION_BIT = 32
+        FLAG_BITS = SHIFT_BIT | ALT_BIT | CTRL_BIT | MOTION_BIT
 
         # Returns true when *raw* looks like a recognizable mouse sequence (SGR or legacy).
         # Lets the TTYBackend short-circuit and dispatch to MouseParser without allocation.
@@ -41,23 +43,13 @@ module Charming
           nil
         end
 
-        # Parses an SGR-format mouse sequence. Decodes button code, 1-based (col, row),
-        # the modifier "C" (ctrl) and "M" (shift) suffix, and the highlight alt (256-color)
-        # sequence as a heuristic for the alt modifier.
+        # Parses an SGR-format mouse sequence: button code with flag bits, 1-based
+        # (col, row), and the press/release final byte.
         def self.parse_sgr(raw)
           match = raw.match(SGR_PATTERN)
           return nil unless match
 
-          button_code = match[1].to_i
-          col = match[2].to_i - 1
-          row = match[3].to_i - 1
-          mode = match[4]
-
-          ctrl = mode == "C"
-          alt = raw.include?("\e[38;5;")
-          shift = mode == "M"
-
-          Events::MouseEvent.new(button: button_code, x: col, y: row, ctrl: ctrl, alt: alt, shift: shift)
+          build_event(match[1].to_i, match[2].to_i - 1, match[3].to_i - 1, release: match[4] == "m")
         end
 
         # Parses a legacy 3-byte mouse sequence. Each of the 3 bytes has 32 subtracted
@@ -69,12 +61,25 @@ module Charming
           bytes = match[1].bytes
           return nil unless bytes.length == 3
 
-          button_code = bytes[0] - 32
-          col = bytes[1] - 32
-          row = bytes[2] - 32
+          build_event(bytes[0] - 32, bytes[1] - 32, bytes[2] - 32, release: false)
+        end
 
-          Events::MouseEvent.new(button: button_code, x: col, y: row)
+        # Builds a MouseEvent from a raw button *code*, splitting out the modifier
+        # and motion flag bits so `button` carries only the button/wheel identity.
+        def self.build_event(code, x, y, release:)
+          Events::MouseEvent.new(
+            button: code & ~FLAG_BITS,
+            x: x,
+            y: y,
+            shift: code.anybits?(SHIFT_BIT),
+            alt: code.anybits?(ALT_BIT),
+            ctrl: code.anybits?(CTRL_BIT),
+            motion: code.anybits?(MOTION_BIT),
+            release: release
+          )
         end
+
+        private_class_method :build_event
       end
     end
   end

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

@@ -67,6 +67,13 @@ module Charming
         end
       end
 
+      # Forwards pasted text to the inner input and re-filters the suggestions.
+      def handle_paste(event)
+        result = @input.handle_paste(event)
+        clamp_selection if result
+        result
+      end
+
       # Renders the input row followed by the suggestion dropdown.
       def render
         [input_line, *suggestion_lines].join("\n")

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

@@ -41,6 +41,11 @@ module Charming
           nil
         end
 
+        # Default paste handler returns nil (paste ignored). Text fields override.
+        def handle_paste(_event)
+          nil
+        end
+
         # Renders the field as a control line prefixed with ">" (active) or " " (inactive),
         # optionally followed by the help line and any error lines.
         def render(active: false)

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

@@ -27,17 +27,27 @@ module Charming
         # Forwards key events to the underlying TextInput, syncing the value and cursor
         # back into the form state. Returns :handled when the event was consumed.
         def handle_key(event)
+          forward_to_input(:handle_key, event)
+        end
+
+        # Forwards pasted text to the underlying TextInput the same way.
+        def handle_paste(event)
+          forward_to_input(:handle_paste, event)
+        end
+
+        private
+
+        # Sends *message* to a freshly-built TextInput and, when the widget consumed
+        # the event, persists the resulting value and cursor into the form state.
+        def forward_to_input(message, event)
           text_input = input
-          result = text_input.handle_key(event)
-          return nil unless result == :handled
+          return nil unless text_input.public_send(message, event) == :handled
 
           state[:values][name] = text_input.value
           field_state[:cursor] = text_input.cursor
           :handled
         end
 
-        private
-
         # The default value for a freshly-bound field is the *value* passed at construction.
         def default_value
           @initial_value

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

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

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

@@ -29,15 +29,12 @@ module Charming
         # Forwards key events to the underlying TextArea, syncing the value, cursor, offset,
         # and preferred column back into the form state. Returns :handled when consumed.
         def handle_key(event)
-          area = text_area
-          result = area.handle_key(event)
-          return nil unless result == :handled
+          forward_to_text_area(:handle_key, event)
+        end
 
-          state[:values][name] = area.value
-          field_state[:cursor] = area.cursor
-          field_state[:offset] = area.offset
-          field_state[:preferred_column] = area.preferred_column
-          :handled
+        # Forwards pasted text (newlines preserved) to the underlying TextArea the same way.
+        def handle_paste(event)
+          forward_to_text_area(:handle_paste, event)
         end
 
         # Renders the field with its label on the first line, body lines indented, and
@@ -50,6 +47,19 @@ module Charming
 
         private
 
+        # Sends *message* to a freshly-built TextArea and, when the widget consumed the
+        # event, persists the value, cursor, offset, and preferred column into form state.
+        def forward_to_text_area(message, event)
+          area = text_area
+          return nil unless area.public_send(message, event) == :handled
+
+          state[:values][name] = area.value
+          field_state[:cursor] = area.cursor
+          field_state[:offset] = area.offset
+          field_state[:preferred_column] = area.preferred_column
+          :handled
+        end
+
         # The default value for a freshly-bound field is the *value* passed at construction.
         def default_value
           @initial_value

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

@@ -38,6 +38,12 @@ module Charming
         advance_or_submit if key == :enter
       end
 
+      # Forwards pasted text to the currently focused field. Text fields insert it
+      # at their cursor; other fields ignore it.
+      def handle_paste(event)
+        current_field&.handle_paste(event)
+      end
+
       # Forms accept free-typed text (their input/textarea fields do), so printable
       # characters route here before global/content key bindings.
       def captures_text?