clack 0.1.4 → 0.4.1

data/lib/clack/environment.rb

@@ -119,7 +119,7 @@ module Clack
         if windows? && !windows_terminal?
           begin
             IO.console&.respond_to?(:raw)
-          rescue
+          rescue IOError, SystemCallError
             false
           end
         else

data/lib/clack/log.rb

@@ -1,8 +1,34 @@
 # frozen_string_literal: true
 
 module Clack
+  # Styled console logging with consistent formatting.
+  #
+  # Each method prints a message prefixed with a colored symbol. Multi-line
+  # messages are automatically aligned with a continuation bar on subsequent lines.
+  #
+  # Accessed via +Clack.log+:
+  #
+  # @example
+  #   Clack.log.info("Starting build...")
+  #   Clack.log.success("Build completed!")
+  #   Clack.log.warn("Cache is stale")
+  #   Clack.log.error("Build failed")
+  #
   module Log
     class << self
+      # Print a message with a custom or default symbol prefix.
+      #
+      # This is the base method used by all other log methods. Pass +symbol:+
+      # to customize the leading character (useful for extending with your own
+      # log levels).
+      #
+      # @param msg [String] the message to display
+      # @param symbol [String, nil] custom prefix symbol (default: gray bar)
+      # @param output [IO] output stream (default: $stdout)
+      # @return [void]
+      #
+      # @example Custom symbol
+      #   Clack.log.message("Deploying...", symbol: "\u2708")
       def message(msg = "", symbol: nil, output: $stdout)
         symbol ||= Colors.gray(Symbols::S_BAR)
         lines = msg.to_s.lines
@@ -17,23 +43,48 @@ module Clack
         end
       end
 
+      # Print an informational message (blue symbol).
+      #
+      # @param msg [String] the message to display
+      # @param output [IO] output stream (default: $stdout)
+      # @return [void]
       def info(msg, output: $stdout)
         message(msg, symbol: Colors.blue(Symbols::S_INFO), output:)
       end
 
+      # Print a success message (green symbol).
+      #
+      # @param msg [String] the message to display
+      # @param output [IO] output stream (default: $stdout)
+      # @return [void]
       def success(msg, output: $stdout)
         message(msg, symbol: Colors.green(Symbols::S_SUCCESS), output:)
       end
 
+      # Print a step completion message (green submit symbol).
+      #
+      # @param msg [String] the message to display
+      # @param output [IO] output stream (default: $stdout)
+      # @return [void]
       def step(msg, output: $stdout)
         message(msg, symbol: Colors.green(Symbols::S_STEP_SUBMIT), output:)
       end
 
+      # Print a warning message (yellow symbol).
+      #
+      # @param msg [String] the message to display
+      # @param output [IO] output stream (default: $stdout)
+      # @return [void]
       def warn(msg, output: $stdout)
         message(msg, symbol: Colors.yellow(Symbols::S_WARN), output:)
       end
       alias_method :warning, :warn
 
+      # Print an error message (red symbol).
+      #
+      # @param msg [String] the message to display
+      # @param output [IO] output stream (default: $stdout)
+      # @return [void]
       def error(msg, output: $stdout)
         message(msg, symbol: Colors.red(Symbols::S_ERROR), output:)
       end

data/lib/clack/note.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 module Clack
+  # Renders a bordered note box with optional title in the terminal.
   module Note
     class << self
+      # Render a note box to the output stream.
+      #
+      # @param message [String] the note content
+      # @param title [String, nil] optional title displayed above the box
+      # @param output [IO] output stream (default: $stdout)
+      # @return [void]
       def render(message = "", title: nil, output: $stdout)
         lines = message.to_s.lines.map(&:chomp)
         # Add empty lines at start and end like original

data/lib/clack/prompts/autocomplete.rb

@@ -7,7 +7,9 @@ module Clack
     # Combines text input with a filtered option list. Type to filter,
     # use arrow keys to navigate matches, Enter to select.
     #
-    # Filtering searches across value, label, and hint fields.
+    # By default, filtering uses fuzzy matching across value, label, and
+    # hint fields, sorted by relevance score. Supply a custom +filter+
+    # proc to override this behavior.
     #
     # @example Basic usage
     #   color = Clack.autocomplete(
@@ -23,20 +25,32 @@ module Clack
     #     max_items: 10
     #   )
     #
+    # @example Custom filter
+    #   Clack.autocomplete(
+    #     message: "Select command",
+    #     options: commands,
+    #     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
       # @param max_items [Integer] max visible options (default: 5)
       # @param placeholder [String, nil] placeholder text when empty
+      # @param filter [Proc, nil] custom filter proc receiving (option_hash, query_string)
+      #   and returning true/false. When nil, the default fuzzy matching
+      #   across label, value, and hint is used.
       # @param opts [Hash] additional options passed to {Core::Prompt}
-      def initialize(message:, options:, max_items: 5, placeholder: nil, **opts)
+      def initialize(message:, options:, max_items: 5, placeholder: nil, filter: nil, **opts)
         super(message:, **opts)
         @all_options = normalize_options(options)
         @max_items = max_items
         @placeholder = placeholder
+        @filter = filter
         @value = ""
         @cursor = 0
         @selected_index = 0
@@ -49,7 +63,6 @@ module Clack
       def handle_key(key)
         return if terminal_state?
 
-        @state = :active if @state == :error
         action = Core::Settings.action?(key)
 
         case action
@@ -92,14 +105,16 @@ module Clack
         lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
 
-        visible_options.each_with_index do |opt, idx|
+        visible_items.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx
           lines << "#{bar}  #{option_display(opt, actual_idx == @selected_index)}\n"
         end
 
-        lines << "#{bar_end}\n"
-
-        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
+        if @state in :error | :warning
+          lines.concat(validation_message_lines)
+        else
+          lines << "#{bar_end}\n"
+        end
 
         lines.join
       end
@@ -119,36 +134,14 @@ module Clack
       private
 
       def update_filtered
-        query = @value.downcase
-        @filtered = @all_options.select do |opt|
-          opt[:label].downcase.include?(query) ||
-            opt[:value].to_s.downcase.include?(query) ||
-            opt[:hint]&.downcase&.include?(query)
+        @filtered = if @filter
+          @all_options.select { |opt| @filter.call(opt, @value) }
+        else
+          Core::FuzzyMatcher.filter(@all_options, @value)
         end
       end
 
-      def visible_options
-        return @filtered if @filtered.length <= @max_items
-
-        @filtered[@scroll_offset, @max_items]
-      end
-
-      def move_selection(delta)
-        return if @filtered.empty?
-
-        @selected_index = (@selected_index + delta) % @filtered.length
-        update_scroll
-      end
-
-      def update_scroll
-        return unless @filtered.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
-      end
+      def scroll_items = @filtered
 
       def option_display(opt, active)
         hint = (opt[:hint] && active) ? Colors.dim(" (#{opt[:hint]})") : ""

data/lib/clack/prompts/autocomplete_multiselect.rb

@@ -30,6 +30,7 @@ module Clack
     class AutocompleteMultiselect < 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
@@ -37,13 +38,17 @@ module Clack
       # @param placeholder [String, nil] placeholder text when empty
       # @param required [Boolean] require at least one selection (default: true)
       # @param initial_values [Array, nil] values to pre-select
+      # @param filter [Proc, nil] custom filter proc receiving (option_hash, query_string)
+      #   and returning true/false. When nil, the default fuzzy matching
+      #   across label, value, and hint is used.
       # @param opts [Hash] additional options passed to {Core::Prompt}
-      def initialize(message:, options:, max_items: 5, placeholder: nil, required: true, initial_values: nil, **opts)
+      def initialize(message:, options:, max_items: 5, placeholder: nil, required: true, initial_values: nil, filter: nil, **opts)
         super(message:, **opts)
         @all_options = normalize_options(options)
         @max_items = max_items
         @placeholder = placeholder
         @required = required
+        @filter = filter
         @search_text = ""
         @cursor = 0
         @selected_index = 0
@@ -57,7 +62,6 @@ module Clack
       def handle_key(key)
         return if terminal_state?
 
-        @state = :active if @state == :error
         action = Core::Settings.action?(key)
 
         case action
@@ -123,7 +127,7 @@ module Clack
 
       def submit_selection
         if @required && @selected_values.empty?
-          @error_message = "Please select at least one option"
+          @error_message = "Please select at least one option. Press #{Colors.cyan("space")} to select, #{Colors.cyan("enter")} to submit"
           @state = :error
           return
         end
@@ -137,9 +141,9 @@ module Clack
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
         lines << help_line
-        lines << "#{active_bar}  #{Colors.dim("Search:")} #{search_input_display}#{match_count}\n"
+        lines << "#{active_bar}  #{Colors.dim("Search:")} #{input_display}#{match_count}\n"
 
-        visible_options.each_with_index do |opt, idx|
+        visible_items.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx
           lines << "#{active_bar}  #{option_display(opt, actual_idx == @selected_index)}\n"
         end
@@ -149,9 +153,10 @@ module Clack
         lines << "#{active_bar}  #{instructions}\n"
         lines << "#{bar_end}\n"
 
-        if @state == :error
-          lines[-2] = "#{Colors.yellow(Symbols::S_BAR)}  #{Colors.yellow(@error_message)}\n"
-          lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}\n"
+        validation_lines = validation_message_lines
+        if validation_lines.any?
+          lines[-1] = validation_lines.first
+          lines.concat(validation_lines[1..])
         end
 
         lines.join
@@ -174,45 +179,19 @@ module Clack
 
       private
 
-      # Override TextInputHelper methods to use @search_text instead of @value
-      def search_input_display
-        return placeholder_display if @search_text.empty?
+      # Use @search_text as text input backing store
+      def text_value = @search_text
 
-        search_value_with_cursor
+      def text_value=(val)
+        @search_text = val
       end
 
-      def search_value_with_cursor
-        chars = @search_text.grapheme_clusters
-        return "#{@search_text}#{cursor_block}" if @cursor >= chars.length
-
-        before = chars[0...@cursor].join
-        current = Colors.inverse(chars[@cursor])
-        after = chars[(@cursor + 1)..].join
-        "#{before}#{current}#{after}"
-      end
-
-      # Override to work with @search_text instead of @value
       def handle_text_input(key)
-        return false unless Core::Settings.printable?(key)
-
-        chars = @search_text.grapheme_clusters
-
-        if Core::Settings.backspace?(key)
-          return false if @cursor.zero?
-
-          chars.delete_at(@cursor - 1)
-          @search_text = chars.join
-          @cursor -= 1
-        else
-          chars.insert(@cursor, key)
-          @search_text = chars.join
-          @cursor += 1
-        end
+        return unless super
 
         @selected_index = 0
         @scroll_offset = 0
         update_filtered
-        true
       end
 
       def match_count
@@ -232,36 +211,14 @@ module Clack
       end
 
       def update_filtered
-        query = @search_text.downcase
-        @filtered = @all_options.select do |opt|
-          opt[:label].downcase.include?(query) ||
-            opt[:value].to_s.downcase.include?(query) ||
-            opt[:hint]&.downcase&.include?(query)
+        @filtered = if @filter
+          @all_options.select { |opt| @filter.call(opt, @search_text) }
+        else
+          Core::FuzzyMatcher.filter(@all_options, @search_text)
         end
       end
 
-      def visible_options
-        return @filtered if @filtered.length <= @max_items
-
-        @filtered[@scroll_offset, @max_items]
-      end
-
-      def move_selection(delta)
-        return if @filtered.empty?
-
-        @selected_index = (@selected_index + delta) % @filtered.length
-        update_scroll
-      end
-
-      def update_scroll
-        return unless @filtered.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
-      end
+      def scroll_items = @filtered
 
       def option_display(opt, active)
         is_selected = @selected_values.include?(opt[:value])

data/lib/clack/prompts/date.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Clack
+  module Prompts
+    # Date picker prompt with inline segmented input.
+    #
+    # Features:
+    # - Three formats: :iso (YYYY-MM-DD), :us (MM/DD/YYYY), :eu (DD/MM/YYYY)
+    # - Arrow key navigation between segments
+    # - Up/down to increment/decrement values
+    # - Direct digit typing with auto-advance
+    # - Min/max date bounds validation
+    #
+    # @example Basic usage
+    #   date = Clack.date(message: "Select a date")
+    #
+    # @example With bounds
+    #   date = Clack.date(
+    #     message: "When?",
+    #     min: Date.today,
+    #     max: Date.today + 365,
+    #     format: :us
+    #   )
+    #
+    class Date < Core::Prompt
+      # Supported date format configurations mapping format symbol to segment order and separator.
+      FORMATS = {
+        iso: {order: [:year, :month, :day], sep: "-"},
+        us: {order: [:month, :day, :year], sep: "/"},
+        eu: {order: [:day, :month, :year], sep: "/"}
+      }.freeze
+
+      # Non-leap-year days per month (index 1-12; index 0 unused).
+      DAYS_IN_MONTH = [nil, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
+      KEY_SHIFT_TAB = "\e[Z" # ANSI escape sequence for Shift+Tab
+
+      # @param message [String] the prompt message
+      # @param format [Symbol] date format (:iso, :us, :eu)
+      # @param initial_value [Date, Time, String, nil] initial date value
+      # @param min [Date, nil] minimum allowed date
+      # @param max [Date, nil] maximum allowed date
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, format: :iso, initial_value: nil, min: nil, max: nil, **opts)
+        super(message:, **opts)
+
+        raise ArgumentError, "Unknown format: #{format}" unless FORMATS.key?(format)
+        raise ArgumentError, "min must be before or equal to max" if min && max && min > max
+
+        @format = format
+        @min = min
+        @max = max
+        @segment = 0
+        @input_buffer = ""
+
+        init_date(initial_value)
+      end
+
+      protected
+
+      def handle_input(key, action)
+        case action
+        when :left then move_segment(-1)
+        when :right then move_segment(1)
+        when :up then adjust_segment(1)
+        when :down then adjust_segment(-1)
+        else
+          case key
+          when "\t" then move_segment(1)
+          when KEY_SHIFT_TAB then move_segment(-1)
+          when /\A\d\z/ then handle_digit(key)
+          end
+        end
+      end
+
+      def submit
+        @value = ::Date.new(@year, @month, @day)
+        super
+      rescue ArgumentError
+        @error_message = friendly_date_error
+        @state = :error
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
+        lines << "#{active_bar}  #{date_display}\n"
+        lines << "#{bar_end}\n" if %i[active initial].include?(@state)
+
+        validation_lines = validation_message_lines
+        if validation_lines.any?
+          lines[-1] = validation_lines.first
+          lines.concat(validation_lines[1..])
+        end
+
+        lines.join
+      end
+
+      def build_final_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+
+        display_text = formatted_date
+        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(display_text)) : Colors.dim(display_text)
+        lines << "#{bar}  #{display}\n"
+
+        lines.join
+      end
+
+      private
+
+      def init_date(initial)
+        date = parse_initial(initial)
+        date = clamp_to_bounds(date)
+        @year = date.year
+        @month = date.month
+        @day = date.day
+      end
+
+      def parse_initial(initial)
+        case initial
+        when ::Date then initial
+        when ::Time then initial.to_date
+        when String then ::Date.parse(initial)
+        else ::Date.today
+        end
+      rescue ::Date::Error
+        ::Date.today
+      end
+
+      def clamp_to_bounds(date)
+        return @min if @min && date < @min
+        return @max if @max && date > @max
+
+        date
+      end
+
+      # Enforce min/max bounds on the current @year/@month/@day components.
+      # Constructs a temporary Date (after clamping day to valid range) and
+      # writes back if the date falls outside the allowed bounds.
+      def enforce_bounds
+        return unless @min || @max
+
+        clamp_day_to_month
+        date = ::Date.new(@year, @month, @day)
+        clamped = clamp_to_bounds(date)
+        return if clamped == date
+
+        @year = clamped.year
+        @month = clamped.month
+        @day = clamped.day
+      end
+
+      def move_segment(delta)
+        commit_input_buffer
+        @segment = (@segment + delta) % 3
+        @input_buffer = ""
+      end
+
+      def adjust_segment(delta)
+        commit_input_buffer
+        @input_buffer = ""
+
+        case current_segment_type
+        when :year
+          @year = (@year + delta).clamp(1, 9999)
+          clamp_day_to_month
+        when :month
+          @month += delta
+          @month = wrap_value(@month, 1, 12)
+          clamp_day_to_month
+        when :day
+          max_day = days_in_month(@year, @month)
+          @day = wrap_value(@day + delta, 1, max_day)
+        end
+
+        enforce_bounds
+      end
+
+      def wrap_value(val, min, max)
+        return min if val > max
+        return max if val < min
+
+        val
+      end
+
+      def handle_digit(digit)
+        @input_buffer += digit
+        expected_length = (current_segment_type == :year) ? 4 : 2
+
+        if @input_buffer.length >= expected_length
+          commit_input_buffer
+          move_segment(1) unless @segment == 2
+        end
+      end
+
+      def commit_input_buffer
+        return if @input_buffer.empty?
+
+        value = @input_buffer.to_i
+        @input_buffer = ""
+
+        case current_segment_type
+        when :year
+          @year = value.clamp(1, 9999)
+          clamp_day_to_month
+        when :month
+          @month = value.clamp(1, 12)
+          clamp_day_to_month
+        when :day
+          @day = value.clamp(1, days_in_month(@year, @month))
+        end
+
+        enforce_bounds
+      end
+
+      def current_segment_type = FORMATS[@format][:order][@segment]
+
+      def days_in_month(year, month)
+        return 29 if month == 2 && leap_year?(year)
+
+        DAYS_IN_MONTH[month]
+      end
+
+      def leap_year?(year) = ::Date.leap?(year)
+
+      def clamp_day_to_month
+        max_day = days_in_month(@year, @month)
+        @day = max_day if @day > max_day
+      end
+
+      def formatted_date
+        fmt = FORMATS[@format]
+        fmt[:order].map { |type|
+          case type
+          when :year then @year.to_s.rjust(4, "0")
+          when :month then @month.to_s.rjust(2, "0")
+          when :day then @day.to_s.rjust(2, "0")
+          end
+        }.join(fmt[:sep])
+      end
+
+      def date_display
+        fmt = FORMATS[@format]
+        fmt[:order].each_with_index.map { |type, idx|
+          text = segment_text_for(type)
+          (idx == @segment) ? Colors.inverse(text) : text
+        }.join(fmt[:sep])
+      end
+
+      def segment_text_for(type)
+        showing_buffer = !@input_buffer.empty? && current_segment_type == type
+        case type
+        when :year
+          showing_buffer ? @input_buffer.ljust(4, "_") : @year.to_s.rjust(4, "0")
+        when :month
+          showing_buffer ? @input_buffer.ljust(2, "_") : @month.to_s.rjust(2, "0")
+        when :day
+          showing_buffer ? @input_buffer.ljust(2, "_") : @day.to_s.rjust(2, "0")
+        end
+      end
+
+      def friendly_date_error
+        max_day = days_in_month(@year, @month)
+        month_name = ::Date::MONTHNAMES[@month]
+
+        if @day > max_day
+          leap_note = (@month == 2 && !leap_year?(@year)) ? " (not a leap year)" : ""
+          "#{month_name} #{@year} has #{max_day} days#{leap_note}"
+        else
+          "Invalid date"
+        end
+      end
+    end
+  end
+end