clack 0.4.6 → 0.6.0

data/lib/clack/box.rb

@@ -39,10 +39,10 @@ module Clack
         format_border ||= ->(text) { Colors.gray(text) }
         symbols = corner_symbols(rounded).map(&format_border)
         lines = message.to_s.lines.map(&:chomp)
-        box_width = calculate_width(lines, title.length, title_padding, content_padding, width)
+        box_width = calculate_width(lines, Clack::Utils.visible_length(title), title_padding, content_padding, width)
         inner_width = box_width - 2
         max_title_len = inner_width - (title_padding * 2)
-        display_title = (title.length > max_title_len) ? "#{title[0, max_title_len - 3]}..." : title
+        display_title = Clack::Utils.truncate(title, max_title_len)
 
         {
           symbols: symbols,
@@ -56,7 +56,7 @@ module Clack
 
       def render_content_lines(output, ctx, content_align, content_padding)
         ctx[:lines].each do |line|
-          left_pad, right_pad = padding_for_line(line.length, ctx[:inner_width], content_padding, content_align)
+          left_pad, right_pad = padding_for_line(Clack::Utils.visible_length(line), ctx[:inner_width], content_padding, content_align)
           output.puts "#{ctx[:v_symbol]}#{" " * left_pad}#{line}#{" " * right_pad}#{ctx[:v_symbol]}"
         end
       end
@@ -82,8 +82,8 @@ module Clack
       def calculate_width(lines, title_len, title_padding, content_padding, width)
         return width + 2 if width.is_a?(Integer) # Add 2 for borders
 
-        # Auto width: fit to content
-        max_line = lines.map(&:length).max || 0
+        # Auto width: fit to content using display width
+        max_line = lines.map { |l| Clack::Utils.visible_length(l) }.max || 0
         title_with_padding = title_len + (title_padding * 2)
         content_with_padding = max_line + (content_padding * 2)
 
@@ -94,7 +94,7 @@ module Clack
         if title.empty?
           "#{symbols[0]}#{h_symbol * inner_width}#{symbols[1]}"
         else
-          left_pad, right_pad = padding_for_line(title.length, inner_width, title_padding, title_align)
+          left_pad, right_pad = padding_for_line(Clack::Utils.visible_length(title), inner_width, title_padding, title_align)
           "#{symbols[0]}#{h_symbol * left_pad}#{title}#{h_symbol * right_pad}#{symbols[1]}"
         end
       end

data/lib/clack/core/fuzzy_matcher.rb

@@ -109,10 +109,10 @@ module Clack
 
         def best_score(opt, query, q_down)
           scores = [
-            score(query, opt[:label], q_down: q_down),
-            score(query, opt[:value].to_s, q_down: q_down)
+            score(query, opt.label, q_down: q_down),
+            score(query, opt.value.to_s, q_down: q_down)
           ]
-          scores << score(query, opt[:hint], q_down: q_down) if opt[:hint]
+          scores << score(query, opt.hint, q_down: q_down) if opt.hint
           scores.max
         end
       end

data/lib/clack/core/key_reader.rb

@@ -16,34 +16,44 @@ module Clack
       SEQUENCE_TIMEOUT = 0.01
 
       class << self
-        # Read a single keystroke from the terminal in raw mode.
-        # Handles multi-byte escape sequences (arrow keys, etc.).
+        # Read a single keystroke in raw mode.
+        # When input is an IO backed by a console, uses raw mode.
+        # When input is a StringIO or test double, reads directly.
         #
+        # @param input [IO, nil] input stream (defaults to IO.console)
         # @return [String, nil] the key code, or nil on EOF
-        # @raise [IOError] if no console is available
-        def read
-          console = IO.console
-          raise IOError, "No console available (not a TTY?)" unless console
+        def read(input = nil)
+          io = input || IO.console
+          raise IOError, "No console available (not a TTY?)" unless io
 
-          console.raw do |io|
-            char = io.getc
-            return char if char.nil? # EOF
-            return char unless char == "\e"
+          # StringIO / test doubles don't support raw mode
+          return read_from(io) unless io.respond_to?(:raw)
 
-            # Check for escape sequence - wait briefly for follow-up
-            return char unless IO.select([io], nil, nil, ESCAPE_TIMEOUT)
-
-            seq = io.getc.to_s
-            return "\e#{seq}" unless seq == "["
-
-            # Read CSI sequence until no more characters arrive
-            seq += io.getc.to_s while IO.select([io], nil, nil, SEQUENCE_TIMEOUT)
-            "\e[#{seq[1..]}"
-          end
+          io.raw { |raw_io| read_from(raw_io) }
         rescue Errno::EIO, Errno::EBADF, IOError
           # Terminal disconnected or closed - treat as cancel
           "\u0003" # Ctrl+C
         end
+
+        private
+
+        def read_from(io)
+          char = io.getc
+          return char if char.nil? # EOF
+          return char unless char == "\e"
+
+          # Check for escape sequence - wait briefly for follow-up
+          return char unless io.respond_to?(:wait_readable) && io.wait_readable(ESCAPE_TIMEOUT)
+
+          seq = io.getc.to_s
+          return "\e#{seq}" unless seq == "["
+
+          # Read CSI sequence until no more characters arrive
+          while io.respond_to?(:wait_readable) && io.wait_readable(SEQUENCE_TIMEOUT)
+            seq += io.getc.to_s
+          end
+          "\e[#{seq[1..]}"
+        end
       end
     end
   end

data/lib/clack/core/options_helper.rb

@@ -2,8 +2,41 @@
 
 module Clack
   module Core
-    # Shared functionality for option-based prompts (Select, Multiselect).
+    # Value object for normalized select-style options.
+    Option = Data.define(:value, :label, :hint, :disabled) do
+      def to_s = label.to_s
+
+      # Hash-style read access for backward compatibility with code (e.g.
+      # custom autocomplete filters) written against the old option hashes.
+      def [](key) = to_h[key]
+    end
+
+    # Value object for select_key options (includes :key).
+    SelectKeyOption = Data.define(:value, :label, :key, :hint) do
+      def to_s = label.to_s
+      def [](key) = to_h[key]
+    end
+
+    # Value objects for group_multiselect flat list (replaces :type discriminator hashes).
+    # GroupOption carries extra fields only used within GroupMultiselect for layout.
+    GroupHeader = Data.define(:label, :options) do
+      def [](key) = to_h[key]
+    end
+    GroupOption = Data.define(:value, :label, :hint, :disabled, :group, :last_in_group) do
+      def to_s = label.to_s
+      def [](key) = to_h[key]
+    end
+
+    # Shared functionality for option-based prompts (Select, Multiselect, Autocomplete, etc.).
     # Handles option normalization, cursor navigation, and scrolling.
+    #
+    # Including classes must define:
+    # - +@max_items+ [Integer, nil] maximum visible items (nil = show all)
+    # - +@option_index+ [Integer] current selection index
+    # - +@scroll_offset+ [Integer] current scroll position
+    #
+    # Including classes must implement:
+    # - +navigable_items+ [Array] returns the current list to navigate
     module OptionsHelper
       # Normalize options to a consistent hash format.
       # Accepts strings, symbols, or hashes with value/label/hint/disabled keys.
@@ -14,18 +47,23 @@ module Clack
       def normalize_options(options)
         raise ArgumentError, "options cannot be empty" if options.nil? || options.empty?
 
-        options.map do |opt|
-          case opt
-          when Hash
-            {
-              value: opt[:value],
-              label: opt[:label] || opt[:value].to_s,
-              hint: opt[:hint],
-              disabled: opt[:disabled] || false
-            }
-          else
-            {value: opt, label: opt.to_s, hint: nil, disabled: false}
-          end
+        options.map { |opt| OptionsHelper.normalize_option(opt) }
+      end
+
+      # Normalize a single option to an Option value object.
+      # @param opt [Hash, String, Symbol] Raw option
+      # @return [Option] Normalized option
+      def self.normalize_option(opt)
+        case opt
+        when Hash
+          Option.new(
+            value: opt[:value],
+            label: opt[:label] || opt[:value].to_s,
+            hint: opt[:hint],
+            disabled: opt[:disabled] || false
+          )
+        else
+          Option.new(value: opt, label: opt.to_s, hint: nil, disabled: false)
         end
       end
 
@@ -36,11 +74,12 @@ module Clack
       # @param delta [Integer] Direction (+1 for forward, -1 for backward)
       # @return [Integer] Index of next enabled option, or from if all disabled
       def find_next_enabled(from, delta)
-        max = @options.length
+        items = navigable_items
+        max = items.length
         idx = (from + delta) % max
 
         max.times do
-          return idx unless @options[idx][:disabled]
+          return idx unless items[idx].disabled
 
           idx = (idx + delta) % max
         end
@@ -48,11 +87,29 @@ module Clack
         from
       end
 
-      # Move cursor in the given direction, skipping disabled options.
+      # Index of the first enabled option.
+      # @return [Integer]
+      def first_enabled_index
+        find_next_enabled(-1, 1)
+      end
+
+      # Move option_index in the given direction, skipping disabled options.
       #
       # @param delta [Integer] Direction (+1 for down/right, -1 for up/left)
       def move_cursor(delta)
-        @cursor = find_next_enabled(@cursor, delta)
+        @option_index = find_next_enabled(@option_index, delta)
+        update_scroll
+      end
+
+      # Move the selection index by delta, wrapping around.
+      # Unlike move_cursor, does not skip disabled items.
+      #
+      # @param delta [Integer] direction (+1 for down, -1 for up)
+      def move_selection(delta)
+        items = navigable_items
+        return if items.empty?
+
+        @option_index = (@option_index + delta) % items.length
         update_scroll
       end
 
@@ -60,19 +117,21 @@ module Clack
       #
       # @return [Array<Hash>] Visible options
       def visible_options
-        return @options unless @max_items && @options.length > @max_items
+        items = navigable_items
+        return items unless @max_items && items.length > @max_items
 
-        @options[@scroll_offset, @max_items]
+        items[@scroll_offset, @max_items]
       end
 
-      # Update scroll offset to keep cursor visible within the window.
+      # Update scroll offset to keep option_index visible within the window.
       def update_scroll
-        return unless @max_items && @options.length > @max_items
+        items = navigable_items
+        return unless @max_items && items.length > @max_items
 
-        if @cursor < @scroll_offset
-          @scroll_offset = @cursor
-        elsif @cursor >= @scroll_offset + @max_items
-          @scroll_offset = @cursor - @max_items + 1
+        if @option_index < @scroll_offset
+          @scroll_offset = @option_index
+        elsif @option_index >= @scroll_offset + @max_items
+          @scroll_offset = @option_index - @max_items + 1
         end
       end
 
@@ -81,15 +140,23 @@ module Clack
       # @param initial_value [Object, nil] Initial value to select
       # @return [Integer] Cursor position
       def find_initial_cursor(initial_value)
-        return 0 if @options.empty?
+        items = navigable_items
+        return 0 if items.empty?
 
         if initial_value.nil?
           # Start at first enabled option
-          return @options[0][:disabled] ? find_next_enabled(-1, 1) : 0
+          return items[0].disabled ? first_enabled_index : 0
         end
 
-        idx = @options.find_index { |o| o[:value] == initial_value }
-        (idx && !@options[idx][:disabled]) ? idx : find_next_enabled(-1, 1)
+        idx = items.find_index { |o| o.value == initial_value }
+        (idx && !items[idx].disabled) ? idx : first_enabled_index
+      end
+
+      # The list of items to navigate. Override in subclasses that use
+      # a filtered or dynamic list (e.g., Autocomplete uses @filtered).
+      # @return [Array]
+      def navigable_items
+        @options
       end
     end
   end

data/lib/clack/core/prompt.rb

@@ -33,9 +33,12 @@ module Clack
 
       # Track active prompts for SIGWINCH notification.
       @active_prompts = []
+      # Signal-safe flag set by SIGWINCH handler; checked in render loop.
+      @resize_pending = false
 
       class << self
         attr_reader :active_prompts
+        attr_accessor :resize_pending
 
         # Register a prompt instance for resize notifications
         def register(prompt)
@@ -47,14 +50,23 @@ module Clack
           @active_prompts.delete(prompt)
         end
 
+        # Notify all active prompts of a pending resize.
+        # Called from the render loop, not from the signal handler.
+        def flush_resize
+          return unless @resize_pending
+
+          @resize_pending = false
+          @active_prompts.each(&:request_redraw)
+        end
+
         # Set up SIGWINCH handler (called once on load).
-        # Signal handlers must avoid mutex/complex operations.
+        # Signal handler only sets a flag -- no allocation or iteration.
         def setup_signal_handler
           return if Clack::Environment.windows?
           return unless Signal.list.key?("WINCH")
 
           Signal.trap("WINCH") do
-            @active_prompts.dup.each(&:request_redraw)
+            @resize_pending = true
           end
         end
       end
@@ -87,7 +99,6 @@ module Clack
         @warning_message = nil
         @warning_confirmed = false
         @prev_frame = nil
-        @cursor = 0
         @needs_redraw = false
       end
 
@@ -117,7 +128,8 @@ module Clack
           @state = :active
 
           loop do
-            key = KeyReader.read
+            Prompt.flush_resize
+            key = KeyReader.read(@input)
             dispatch_key(key)
             render
 
@@ -175,14 +187,13 @@ module Clack
       # Process a keypress and update state accordingly.
       # Delegates to {#handle_input} for prompt-specific behavior.
       #
-      # Override this in subclasses that need custom key dispatch (e.g., Select,
-      # Confirm, Autocomplete). The warning state and error-clearing are handled
-      # by {#dispatch_key} before this method is called, so overrides do not need
-      # to manage those transitions.
+      # Extension points (simplest to most powerful):
+      # - Override {#handle_input} for navigation/printable input only
+      # - Override {#can_submit?} to guard enter (e.g., disabled options)
+      # - Override {#handle_key} for full custom key dispatch
       #
-      # For prompts that only need custom handling of printable/navigation input
-      # (not cancel/enter), override {#handle_input} instead. That is simpler and
-      # preserves the default cancel/enter behavior from this method.
+      # The warning state and error-clearing are handled by {#dispatch_key}
+      # before this method is called.
       #
       # @param key [String] the key code from {KeyReader}
       def handle_key(key)
@@ -194,12 +205,17 @@ module Clack
         when :cancel
           @state = :cancel
         when :enter
-          submit
+          submit if can_submit?
         else
           handle_input(key, action)
         end
       end
 
+      # Guard hook for submit. Override to prevent submission in certain states
+      # (e.g., when cursor is on a disabled option in Select).
+      # @return [Boolean] true if submit should proceed
+      def can_submit? = true
+
       # Handle prompt-specific input. Override in subclasses.
       #
       # This is the simplest extension point for prompts that only need to handle
@@ -348,6 +364,7 @@ module Clack
         submit
         if @state == :error
           $stderr.print "#{Colors.yellow("!")}  #{Colors.yellow("CI mode: validation failed for")} \"#{@message}\": #{@error_message}\n"
+          return CANCEL
         end
         @value
       end
@@ -418,6 +435,22 @@ module Clack
         end
       end
 
+      # Common frame header: bar + symbol/message + help line.
+      # @return [String] header lines
+      def frame_header
+        "#{bar}\n#{symbol_for_state}  #{@message}\n#{help_line}"
+      end
+
+      # Common frame footer: validation messages or bar_end.
+      # Replaces the repeated pattern of splicing validation lines.
+      # @return [String] footer lines
+      def frame_footer
+        vlns = validation_message_lines
+        return vlns.join if vlns.any?
+
+        "#{bar_end}\n"
+      end
+
       # Build validation message lines for error or warning states.
       # Returns array of lines to append, or empty array if no validation message.
       def validation_message_lines

data/lib/clack/core/scroll_helper.rb

@@ -2,52 +2,21 @@
 
 module Clack
   module Core
-    # Shared scroll/navigation logic for filterable option lists.
-    #
-    # Used by prompts that have a dynamically filtered list (Autocomplete,
-    # AutocompleteMultiselect, Path) where the user navigates a subset of
-    # options that changes as they type.
-    #
-    # Including classes must define:
-    # - +@max_items+ [Integer] maximum visible items
-    # - +@selected_index+ [Integer] current selection index
-    # - +@scroll_offset+ [Integer] current scroll position
-    #
-    # Including classes must implement:
-    # - +scroll_items+ [Array] returns the current filterable list
+    # @deprecated Use {OptionsHelper} directly. ScrollHelper is now an alias
+    #   for backwards compatibility.
     module ScrollHelper
-      # Get the currently visible slice of items based on scroll position.
-      #
-      # @return [Array] visible items
-      def visible_items
-        items = scroll_items
-        return items if items.length <= @max_items
-
-        items[@scroll_offset, @max_items]
+      def self.included(base)
+        base.include(OptionsHelper) unless base.ancestors.include?(OptionsHelper)
       end
 
-      # Move the selection index by delta, wrapping around.
-      #
-      # @param delta [Integer] direction (+1 for down, -1 for up)
-      def move_selection(delta)
-        items = scroll_items
-        return if items.empty?
-
-        @selected_index = (@selected_index + delta) % items.length
-        update_selection_scroll
+      # Alias for visible_options (old name from when ScrollHelper was separate)
+      def visible_items
+        visible_options
       end
 
-      private
-
-      # Update scroll offset to keep the selected index visible.
-      def update_selection_scroll
-        return unless scroll_items.length > @max_items
-
-        if @selected_index < @scroll_offset
-          @scroll_offset = @selected_index
-        elsif @selected_index >= @scroll_offset + @max_items
-          @scroll_offset = @selected_index - @max_items + 1
-        end
+      # Alias for navigable_items (old name from when ScrollHelper was separate)
+      def scroll_items
+        navigable_items
       end
     end
   end

data/lib/clack/core/selection_manager.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    # Shared selection management for multi-select prompts.
+    # Handles toggle, toggle-all, required validation, and value tracking.
+    #
+    # Including classes must define:
+    # - +@selected+ [Set] the set of selected values
+    # - +@required+ [Boolean] whether at least one selection is required
+    module SelectionManager
+      REQUIRED_ERROR = "Please select at least one option. Press %s to select, %s to submit"
+
+      # Toggle a value in the selection set.
+      # @param value [Object] the value to toggle
+      def toggle_value(value)
+        if @selected.include?(value)
+          @selected.delete(value)
+        else
+          @selected.add(value)
+        end
+      end
+
+      # Validate that selection meets requirements before submit.
+      # Sets error state if required and empty.
+      # @return [Boolean] true if valid to proceed with submit
+      def validate_selection
+        if @required && @selected.empty?
+          @error_message = format(REQUIRED_ERROR, Colors.cyan("space"), Colors.cyan("enter"))
+          @state = :error
+          return false
+        end
+        true
+      end
+
+      # Update @value from the current selection.
+      def update_selection_value
+        @value = @selected.to_a
+      end
+
+      # Build the final display string from selected options.
+      # @param all_options [Array<Hash>] the full options list to match against
+      # @return [String] comma-separated labels
+      def selected_labels(all_options)
+        all_options.select { |o| @selected.include?(o.value) }.map { |o| o.label }.join(", ")
+      end
+    end
+  end
+end

data/lib/clack/note.rb

@@ -14,14 +14,15 @@ module Clack
         lines = message.to_s.lines.map(&:chomp)
         # Add empty lines at start and end like original
         lines = ["", *lines, ""]
-        title_len = title&.length || 0
+        title_len = Clack::Utils.visible_length(title)
         width = calculate_width(lines, title_len)
 
         output.puts Colors.gray(Symbols::S_BAR)
         output.puts build_top_border(title, title_len, width)
 
         lines.each do |line|
-          padded = line.ljust(width)
+          pad = width - Clack::Utils.visible_length(line)
+          padded = pad.positive? ? line + (" " * pad) : line
           output.puts "#{Colors.gray(Symbols::S_BAR)}  #{Colors.dim(padded)}#{Colors.gray(Symbols::S_BAR)}"
         end
 
@@ -31,7 +32,7 @@ module Clack
       private
 
       def calculate_width(lines, title_len)
-        max_line = lines.map(&:length).max || 0
+        max_line = lines.map { |line| Clack::Utils.visible_length(line) }.max || 0
         [max_line, title_len].max + 2
       end
 

data/lib/clack/prompts/autocomplete.rb

@@ -29,13 +29,12 @@ module Clack
     #   Clack.autocomplete(
     #     message: "Select command",
     #     options: commands,
-    #     filter: ->(opt, query) { opt[:label].start_with?(query) }
+    #     filter: ->(opt, query) { opt.label.start_with?(query) }
     #   )
     #
     class Autocomplete < Core::Prompt
       include Core::OptionsHelper
       include Core::TextInputHelper
-      include Core::ScrollHelper
 
       # @param message [String] the prompt message
       # @param options [Array<Hash, String>] list of options to filter
@@ -51,9 +50,9 @@ module Clack
         @max_items = max_items
         @placeholder = placeholder
         @filter = filter
-        @value = ""
+        @search_text = ""
         @cursor = 0
-        @selected_index = 0
+        @option_index = 0
         @scroll_offset = 0
         update_filtered
       end
@@ -81,10 +80,17 @@ module Clack
         end
       end
 
+      # Use @search_text as text input backing store
+      def text_value = @search_text
+
+      def text_value=(val)
+        @search_text = val
+      end
+
       def handle_text_input(key)
         return unless super
 
-        @selected_index = 0
+        @option_index = 0
         @scroll_offset = 0
         update_filtered
       end
@@ -96,7 +102,7 @@ module Clack
           return
         end
 
-        @value = @filtered[@selected_index][:value]
+        @value = @filtered[@option_index].value
         submit
       end
 
@@ -107,9 +113,9 @@ module Clack
         lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
 
-        visible_items.each_with_index do |opt, idx|
+        visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx
-          lines << "#{bar}  #{option_display(opt, actual_idx == @selected_index)}\n"
+          lines << "#{bar}  #{option_display(opt, actual_idx == @option_index)}\n"
         end
 
         if @state in :error | :warning
@@ -121,26 +127,26 @@ module Clack
         lines.join
       end
 
-      def final_display = @filtered[@selected_index]&.[](:label) || @value
+      def final_display = @filtered[@option_index]&.label || @value
 
       private
 
       def update_filtered
         @filtered = if @filter
-          @all_options.select { |opt| @filter.call(opt, @value) }
+          @all_options.select { |opt| @filter.call(opt, @search_text) }
         else
-          Core::FuzzyMatcher.filter(@all_options, @value)
+          Core::FuzzyMatcher.filter(@all_options, @search_text)
         end
       end
 
-      def scroll_items = @filtered
+      def navigable_items = @filtered
 
       def option_display(opt, active)
-        hint = (opt[:hint] && active) ? Colors.dim(" (#{opt[:hint]})") : ""
+        hint = (opt.hint && active) ? Colors.dim(" (#{opt.hint})") : ""
         if active
-          "#{Colors.green(Symbols::S_RADIO_ACTIVE)} #{opt[:label]}#{hint}"
+          "#{Colors.green(Symbols::S_RADIO_ACTIVE)} #{opt.label}#{hint}"
         else
-          "#{Colors.dim(Symbols::S_RADIO_INACTIVE)} #{Colors.dim(opt[:label])}"
+          "#{Colors.dim(Symbols::S_RADIO_INACTIVE)} #{Colors.dim(opt.label)}"
         end
       end
     end