clack 0.1.3 → 0.2.0

data/lib/clack/core/settings.rb

@@ -2,6 +2,7 @@
 
 module Clack
   module Core
+    # Global configuration for key bindings, guide bar display, and input classification.
     module Settings
       # Navigation and control actions
       ACTIONS = %i[up down left right space enter cancel].freeze
@@ -78,6 +79,9 @@ module Clack
           @config_mutex.synchronize { @config[:with_guide] }
         end
 
+        # Look up the action mapped to a key code.
+        # @param key [String] key code from {KeyReader}
+        # @return [Symbol, nil] the action (:up, :down, :enter, etc.) or nil
         def action?(key)
           aliases = @config_mutex.synchronize { @config[:aliases] }
           aliases[key] if ACTIONS.include?(aliases[key])

data/lib/clack/core/text_input_helper.rb

@@ -25,10 +25,14 @@ module Clack
         format_placeholder_with_cursor(text)
       end
 
+      # @return [String, nil] the placeholder text, or nil if none set
       def current_placeholder
         defined?(@placeholder) ? @placeholder : nil
       end
 
+      # Render placeholder text with an inverse cursor on the first character.
+      # @param text [String] placeholder text to format
+      # @return [String] formatted placeholder with cursor highlight
       def format_placeholder_with_cursor(text)
         chars = text.grapheme_clusters
         first = chars.first || ""

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 searches across value, label, and hint fields
+    # using a case-insensitive substring match. Supply a custom +filter+
+    # proc to override this behavior.
     #
     # @example Basic usage
     #   color = Clack.autocomplete(
@@ -23,6 +25,13 @@ 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
@@ -31,12 +40,16 @@ module Clack
       # @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 case-insensitive substring
+      #   match 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 +62,6 @@ module Clack
       def handle_key(key)
         return if terminal_state?
 
-        @state = :active if @state == :error
         action = Core::Settings.action?(key)
 
         case action
@@ -97,9 +109,11 @@ module Clack
           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,11 +133,15 @@ 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
+          query = @value.downcase
+          @all_options.select do |opt|
+            opt[:label].downcase.include?(query) ||
+              opt[:value].to_s.downcase.include?(query) ||
+              opt[:hint]&.downcase&.include?(query)
+          end
         end
       end
 

data/lib/clack/prompts/autocomplete_multiselect.rb

@@ -57,7 +57,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 +122,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
@@ -193,17 +192,17 @@ module Clack
 
       # 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 = @search_text.grapheme_clusters
           chars.delete_at(@cursor - 1)
           @search_text = chars.join
           @cursor -= 1
         else
+          return false unless Core::Settings.printable?(key)
+
+          chars = @search_text.grapheme_clusters
           chars.insert(@cursor, key)
           @search_text = chars.join
           @cursor += 1

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

data/lib/clack/prompts/group_multiselect.rb

@@ -2,7 +2,46 @@
 
 module Clack
   module Prompts
+    # Multiple-selection prompt with options organized into named groups.
+    #
+    # Navigate with arrow keys or j/k. Toggle selection with Space.
+    # Groups can optionally be toggled as a whole when +selectable_groups+ is enabled.
+    #
+    # @example Basic usage
+    #   features = Clack.group_multiselect(
+    #     message: "Select features",
+    #     options: [
+    #       { label: "Frontend", options: %w[hotwire stimulus] },
+    #       { label: "Backend", options: %w[sidekiq solid_queue] }
+    #     ]
+    #   )
+    #
+    # @example With selectable groups and spacing
+    #   features = Clack.group_multiselect(
+    #     message: "Select features",
+    #     options: [
+    #       { label: "Frontend", options: [
+    #         { value: "hotwire", label: "Hotwire" },
+    #         { value: "stimulus", label: "Stimulus" }
+    #       ]},
+    #       { label: "Background", options: [
+    #         { value: "sidekiq", label: "Sidekiq" },
+    #         { value: "solid_queue", label: "Solid Queue" }
+    #       ]}
+    #     ],
+    #     selectable_groups: true,
+    #     group_spacing: 1
+    #   )
+    #
     class GroupMultiselect < Core::Prompt
+      # @param message [String] the prompt message
+      # @param options [Array<Hash>] groups, each with :label and :options (Array<Hash, String>)
+      # @param initial_values [Array] values to pre-select
+      # @param required [Boolean] require at least one selection (default: true)
+      # @param selectable_groups [Boolean] allow toggling all options in a group at once (default: false)
+      # @param group_spacing [Integer] number of blank lines between groups (default: 0)
+      # @param cursor_at [Object, nil] value to position cursor at initially
+      # @param opts [Hash] additional options passed to {Core::Prompt}
       def initialize(
         message:,
         options:,
@@ -29,7 +68,6 @@ module Clack
       def handle_key(key)
         return if terminal_state?
 
-        @state = :active if @state == :error
         action = Core::Settings.action?(key)
 
         case action
@@ -48,7 +86,7 @@ module Clack
 
       def submit
         if @required && @selected.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
@@ -67,7 +105,7 @@ module Clack
           is_last_in_group = item[:last_in_group]
 
           # Add group spacing before groups (except first)
-          if is_group && prev_was_group == false && idx.positive? && @group_spacing.positive?
+          if is_group && !prev_was_group && idx.positive? && @group_spacing.positive?
             @group_spacing.times { lines << "#{active_bar}\n" }
           end
 
@@ -102,9 +140,7 @@ module Clack
 
       private
 
-      def normalize_groups(options)
-        options.map { |group| normalize_group(group) }
-      end
+      def normalize_groups(options) = options.map { |group| normalize_group(group) }
 
       def normalize_group(group)
         {
@@ -122,9 +158,7 @@ module Clack
         end
       end
 
-      def build_flat_items
-        @groups.flat_map { |group| flatten_group(group) }
-      end
+      def build_flat_items = @groups.flat_map { |group| flatten_group(group) }
 
       def flatten_group(group)
         group_item = {type: :group, label: group[:label], options: group[:options]}
@@ -138,7 +172,7 @@ module Clack
             last_in_group: idx == group[:options].length - 1
           }
         end
-        [group_item] + option_items
+        [group_item, *option_items]
       end
 
       def selected_options
@@ -153,11 +187,7 @@ module Clack
           return idx if idx
         end
 
-        # Find first selectable item
-        @flat_items.each_with_index do |item, idx|
-          return idx if can_select?(item)
-        end
-        0
+        @flat_items.find_index { |item| can_select?(item) } || 0
       end
 
       def can_select?(item)
@@ -211,9 +241,7 @@ module Clack
         end
       end
 
-      def update_value
-        @value = @selected.to_a
-      end
+      def update_value = @value = @selected.to_a
 
       def group_display(item, active)
         if @selectable_groups