clack 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b2beeffde4af3c88491d8b659dd781e8bd3e652e06f8c159a3ca7910fc69c87
-  data.tar.gz: 86b779a202099d27cf702009ee649e19a49b11305e10d2033cf7a0425fe38e10
+  metadata.gz: c0622f234b9f83906c6440e54c29a12715ecfc7a2b3777ec68efaf3882defcb7
+  data.tar.gz: 450c6376c40ad88a27683294e97292f227e2081ccc90a0c076949bba3e5afd1d
 SHA512:
-  metadata.gz: 9f8b20f670252b17132fcb664eeeaa3ba06b8a8fa0abbee5fdb8e40d17460f2e59badeda5b11b20aaa82b7e9b4b0fef6d06524933794dd20a3c6fcd159cc2115
-  data.tar.gz: 21642c6a8cea0671cff152932e806ea7a83163612ecd35739fa2e2bd98179b5e5b714ae6de3e5a2153206ac5f3b52f02ec2e28fc82541056a726d60071afbdab
+  metadata.gz: '08a7d471122e503168817430b65ad3618488eef6a2c79229a50e20a0a3ff3f2df741faef330a81b57875ddca3a37a68d0aebd19e770b7bbe73addd9a737bc9ec'
+  data.tar.gz: 76e01f5eef142fd64069e1d9ba705edebc5694834ab68d5f7a8370eb345f1bf1473f2f1771d0178ed80e0b6c977c05d032d0059112bf36e72dd2fbe18f3850a3

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [0.4.1] - 2026-02-20
+
+### Fixed
+- `AutocompleteMultiselect` now renders warning validation messages (was error-only)
+- CI mode no longer writes ANSI escape codes to non-TTY output
+- CI mode prints a warning when validation fails instead of silently returning
+- Spinner animation restarts from frame 0 when reused
+- `Environment.raw_mode_supported?` catches specific exceptions instead of bare rescue
+- `FuzzyMatcher.filter` pre-computes downcased query (performance optimization for large lists)
+- Removed dead instance variables in Path, Testing, and Spinner
+- Simplified `Range#clamp` by removing unreachable branch
+
+### Changed
+- Updated gem dependencies (rubocop 1.84, standard 1.54, prism 1.9, bigdecimal 4.0)
+- Autocomplete YARD docs corrected: default filter is fuzzy matching, not substring
+- Expanded YARD `@option` documentation for spinner, multiselect, group_multiselect, path, tasks
+- README and ARCHITECTURE.md updated to cover all v0.3.0-v0.4.0 features
+
+## [0.4.0] - 2026-02-19
+
+### Added
+- `range` slider prompt for numeric selection (`Clack.range(message:, min:, max:, step:, default:)`)
+- Tab completion on `text` prompt via `completions:` parameter (array or proc)
+- Minimum terminal width warning (non-blocking, 40 columns)
+
+### Changed
+- Path prompt caches directory listings to avoid repeated filesystem scans on every keystroke
+
+## [0.3.0] - 2026-02-19
+
+### Added
+- `Clack::Testing` module with first-class test helpers (`simulate`, `simulate_with_output`, `PromptDriver`)
+- `Clack::Core::FuzzyMatcher` with scored fuzzy matching (consecutive/boundary/start bonuses)
+- CI / non-interactive mode: `Clack.update_settings(ci_mode: true)` or `:auto` to auto-detect
+- `autocomplete_multiselect` now accepts `filter:` proc for custom matching logic
+
+### Changed
+- Autocomplete prompts default to fuzzy matching instead of substring matching
+- Spinner is now thread-safe: guards against double-finish, protects `@cancelled` reads with mutex
+
+## [0.2.1] - 2026-02-19
+
+### Added
+- `Core::ScrollHelper` mixin extracted from scroll/filter logic across 3 prompts
+
+### Changed
+- `TextInputHelper` parameterized via `text_value`/`text_value=` for custom backing stores
+- Tasks prompt now reuses `Core::Spinner` instead of inline spinner implementation
+- Removed redundant `@value = nil` from SelectKey
+
 ## [0.2.0] - 2026-02-19
 
 ### Added

data/README.md

@@ -193,7 +193,24 @@ name = Clack.text(
   placeholder: "my-project",       # Shown when empty (dim)
   default_value: "untitled",       # Used if submitted empty
   initial_value: "hello-world",    # Pre-filled, editable
-  validate: ->(v) { "Required!" if v.empty? }
+  validate: ->(v) { "Required!" if v.empty? },
+  help: "Letters, numbers, and dashes only"  # Contextual help text
+)
+```
+
+**Tab completion** - press `Tab` to cycle through matching candidates:
+
+```ruby
+# Tab completion from a static list
+cmd = Clack.text(
+  message: "Command?",
+  completions: %w[build test deploy lint format]
+)
+
+# Dynamic tab completion
+file = Clack.text(
+  message: "File?",
+  completions: ->(input) { Dir.glob("#{input}*") }
 )
 ```
 
@@ -276,7 +293,7 @@ features = Clack.multiselect(
 
 ### Autocomplete
 
-Type to filter from a list of options.
+Type to filter from a list of options. Filtering uses **fuzzy matching** by default -- characters must appear in order but don't need to be consecutive (e.g. "fb" matches "foobar"). Pass `filter:` to override with custom logic.
 
 ```ruby
 color = Clack.autocomplete(
@@ -340,6 +357,20 @@ date = Clack.date(
 
 **Navigation:** `Tab`/`←→` between segments | `↑↓` adjust value | type digits directly
 
+### Range
+
+Numeric selection with a visual slider track. Navigate with `←→` or `↑↓` arrow keys (or `hjkl`).
+
+```ruby
+volume = Clack.range(
+  message: "Set volume",
+  min: 0,
+  max: 100,
+  step: 5,
+  default: 50
+)
+```
+
 ### Select Key
 
 Quick selection using keyboard shortcuts.
@@ -583,8 +614,51 @@ Clack.update_settings(aliases: { "y" => :enter, "n" => :cancel })
 
 # Disable guide bars
 Clack.update_settings(with_guide: false)
+
+# CI / non-interactive mode (prompts auto-submit with defaults)
+Clack.update_settings(ci_mode: true)       # Always on
+Clack.update_settings(ci_mode: :auto)      # Auto-detect (non-TTY or CI env vars)
+```
+
+When CI mode is active, prompts immediately submit with their default values instead of waiting for input. Useful for CI pipelines and scripted environments where stdin is not a TTY.
+
+Clack also warns when terminal width is below 40 columns, since prompts may not render cleanly in very narrow terminals.
+
+## Testing
+
+Clack ships with first-class test helpers. Require `clack/testing` explicitly (it is not auto-loaded):
+
+```ruby
+require "clack/testing"
+
+# Simulate a text prompt
+result = Clack::Testing.simulate(Clack.method(:text), message: "Name?") do |prompt|
+  prompt.type("Alice")
+  prompt.submit
+end
+# => "Alice"
+
+# Capture rendered output alongside the result
+result, output = Clack::Testing.simulate_with_output(Clack.method(:confirm), message: "Sure?") do |prompt|
+  prompt.left   # switch to "No"
+  prompt.submit
+end
 ```
 
+The `PromptDriver` yielded to the block provides these methods:
+
+| Method | Description |
+|---|---|
+| `type(text)` | Type a string character by character |
+| `submit` | Press Enter |
+| `cancel` | Press Escape |
+| `up` / `down` / `left` / `right` | Arrow keys |
+| `toggle` | Press Space (for multiselect) |
+| `tab` | Press Tab |
+| `backspace` | Press Backspace |
+| `ctrl_d` | Press Ctrl+D (submit multiline text) |
+| `key(sym_or_char)` | Press an arbitrary key by symbol (e.g. `:escape`) or raw character |
+
 ## Requirements
 
 - Ruby 3.2+

data/lib/clack/core/ci_mode.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    # Non-interactive mode for CI environments and piped input.
+    #
+    # When enabled, prompts auto-submit with their default values instead
+    # of waiting for user input. Useful for CI pipelines, automated testing,
+    # and scripted usage where stdin isn't a TTY.
+    #
+    # Enable explicitly:
+    #   Clack.update_settings(ci_mode: true)
+    #
+    # Or auto-detect (non-TTY stdin or CI environment variable):
+    #   Clack.update_settings(ci_mode: :auto)
+    module CiMode
+      class << self
+        # Check if CI mode is currently active.
+        #
+        # @return [Boolean]
+        def active?
+          setting = Settings.config[:ci_mode]
+          case setting
+          when true
+            true
+          when :auto
+            !Environment.tty?($stdin) || Environment.ci?
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clack/core/fuzzy_matcher.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    # Simple scored fuzzy matcher for autocomplete prompts.
+    #
+    # Matches query characters in order within the target string, scoring
+    # higher for consecutive matches and matches at word boundaries.
+    # Dependency-free alternative to Levenshtein distance that's fast
+    # enough for interactive use.
+    #
+    # @example Basic matching
+    #   FuzzyMatcher.match?("fb", "foobar")  # => true
+    #   FuzzyMatcher.match?("zz", "foobar")  # => false
+    #
+    # @example Scoring
+    #   FuzzyMatcher.score("fb", "foobar")  # => 2 (non-consecutive)
+    #   FuzzyMatcher.score("foo", "foobar") # => 9 (consecutive + start)
+    #
+    # @example Filtering and sorting options
+    #   FuzzyMatcher.filter(options, "fb") # => sorted by relevance
+    module FuzzyMatcher
+      # Bonus for match at the very start of the string
+      START_BONUS = 3
+      # Bonus for each consecutive character matched
+      CONSECUTIVE_BONUS = 2
+      # Bonus for match at a word boundary (after space, _, -)
+      BOUNDARY_BONUS = 2
+      # Base score per matched character
+      BASE_SCORE = 1
+
+      class << self
+        # Check if query fuzzy-matches the target string.
+        #
+        # @param query [String] the search query
+        # @param target [String] the string to match against
+        # @return [Boolean] true if all query chars appear in order in target
+        def match?(query, target)
+          return true if query.empty?
+
+          qi = 0
+          q_chars = query.downcase
+          t_chars = target.downcase
+
+          t_chars.each_char do |tc|
+            qi += 1 if tc == q_chars[qi]
+            return true if qi >= q_chars.length
+          end
+
+          false
+        end
+
+        # Score a fuzzy match. Higher is better. Returns 0 if no match.
+        #
+        # @param query [String] the search query
+        # @param target [String] the string to score against
+        # @param q_down [String, nil] pre-downcased query (optimization for batch use)
+        # @return [Integer] match score (0 = no match)
+        def score(query, target, q_down: nil)
+          return 0 if query.empty?
+
+          q_down ||= query.downcase
+          t_down = target.downcase
+          qi = 0
+          total = 0
+          prev_match_idx = -2 # -2 so first match at 0 isn't consecutive
+
+          t_down.each_char.with_index do |tc, ti|
+            next unless qi < q_down.length && tc == q_down[qi]
+
+            total += BASE_SCORE
+            total += START_BONUS if ti.zero?
+            total += CONSECUTIVE_BONUS if ti == prev_match_idx + 1
+            total += BOUNDARY_BONUS if ti.positive? && boundary?(t_down[ti - 1])
+
+            prev_match_idx = ti
+            qi += 1
+          end
+
+          (qi >= q_down.length) ? total : 0
+        end
+
+        # Filter and sort option hashes by fuzzy relevance.
+        #
+        # Matches against label, value (as string), and hint fields.
+        # Returns options sorted by best match score (descending).
+        #
+        # @param options [Array<Hash>] normalized option hashes
+        # @param query [String] the search query
+        # @return [Array<Hash>] matching options sorted by relevance
+        def filter(options, query)
+          return options if query.empty?
+
+          q_down = query.downcase
+
+          scored = options.filter_map do |opt|
+            s = best_score(opt, query, q_down)
+            [opt, s] if s.positive?
+          end
+
+          scored.sort_by { |_, s| -s }.map(&:first)
+        end
+
+        private
+
+        def boundary?(char)
+          char == " " || char == "_" || char == "-" || char == "/"
+        end
+
+        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)
+          ]
+          scores << score(query, opt[:hint], q_down: q_down) if opt[:hint]
+          scores.max
+        end
+      end
+    end
+  end
+end

data/lib/clack/core/prompt.rb

@@ -27,6 +27,10 @@ module Clack
     #   end
     #
     class Prompt
+      # Minimum terminal width for clean rendering.
+      # Prompts warn (non-blocking) if the terminal is narrower.
+      MIN_TERMINAL_WIDTH = 40
+
       # Track active prompts for SIGWINCH notification.
       # Signal handler may fire during register/unregister. We can't use
       # .dup (allocates, forbidden in trap context) so we accept a benign
@@ -103,24 +107,32 @@ module Clack
       #
       # @return [Object, Clack::CANCEL] the submitted value or CANCEL sentinel
       def run
+        return run_ci_mode if CiMode.active?
+
         Prompt.register(self)
-        setup_terminal
-        render
-        @state = :active
+        warn_narrow_terminal
+        terminal_setup = false
 
-        loop do
-          key = KeyReader.read
-          dispatch_key(key)
+        begin
+          setup_terminal
+          terminal_setup = true
           render
+          @state = :active
 
-          break if terminal_state?
-        end
+          loop do
+            key = KeyReader.read
+            dispatch_key(key)
+            render
 
-        finalize
-        (terminal_state? && @state == :cancel) ? CANCEL : @value
-      ensure
-        Prompt.unregister(self)
-        cleanup_terminal
+            break if terminal_state?
+          end
+
+          finalize
+          (terminal_state? && @state == :cancel) ? CANCEL : @value
+        ensure
+          Prompt.unregister(self)
+          cleanup_terminal if terminal_setup
+        end
       end
 
       protected
@@ -321,8 +333,30 @@ module Clack
         %i[submit cancel].include?(@state)
       end
 
+      # Auto-submit with current defaults in CI/non-interactive mode.
+      # Subclass submit overrides (e.g., Text applying default_value) run normally.
+      # Validation and transforms are applied. Returns the value regardless of
+      # validation outcome since there's no interactive way to fix input.
+      def run_ci_mode
+        submit
+        if @state == :error
+          @output.print "#{Colors.yellow("!")}  #{Colors.yellow("CI mode: validation failed for")} \"#{@message}\": #{@error_message}\n"
+        end
+        @value
+      end
+
       private
 
+      def warn_narrow_terminal
+        return unless Environment.tty?(@output)
+
+        cols = Environment.columns(@output)
+        return if cols >= MIN_TERMINAL_WIDTH
+
+        @output.print "#{Colors.yellow("!")}  #{Colors.yellow("Terminal is narrow")} " \
+                       "(#{cols} cols, #{MIN_TERMINAL_WIDTH} recommended)\n"
+      end
+
       def setup_terminal
         @output.print Cursor.hide
       end

data/lib/clack/core/scroll_helper.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+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
+    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]
+      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
+      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
+      end
+    end
+  end
+end

data/lib/clack/core/settings.rb

@@ -40,7 +40,8 @@ module Clack
       # Global configuration (mutable)
       @config = {
         aliases: ALIASES.dup,
-        with_guide: true
+        with_guide: true,
+        ci_mode: false
       }
       @config_mutex = Mutex.new
 
@@ -54,11 +55,13 @@ module Clack
         # Update global settings
         # @param aliases [Hash, nil] Custom key to action mappings (merged with defaults)
         # @param with_guide [Boolean, nil] Whether to show guide bars
+        # @param ci_mode [Boolean, Symbol, nil] CI mode: true (always), :auto (detect), false (never)
         # @return [Hash] Updated configuration
-        def update(aliases: nil, with_guide: nil)
+        def update(aliases: nil, with_guide: nil, ci_mode: nil)
           @config_mutex.synchronize do
             @config[:aliases] = ALIASES.merge(aliases) if aliases
             @config[:with_guide] = with_guide unless with_guide.nil?
+            @config[:ci_mode] = ci_mode unless ci_mode.nil?
             @config.dup
           end
         end
@@ -68,7 +71,8 @@ module Clack
           @config_mutex.synchronize do
             @config = {
               aliases: ALIASES.dup,
-              with_guide: true
+              with_guide: true,
+              ci_mode: false
             }
           end
         end

data/lib/clack/core/text_input_helper.rb

@@ -4,12 +4,16 @@ module Clack
   module Core
     # Shared functionality for text input prompts (Text, Autocomplete, Path).
     # Handles cursor display, placeholder rendering, and text manipulation.
+    #
+    # By default operates on +@value+ and +@cursor+. Override
+    # +text_value+ and +text_value=+ in your class to use a different
+    # backing store (e.g. +@search_text+ in AutocompleteMultiselect).
     module TextInputHelper
       # Display the input field with cursor or placeholder.
       #
       # @return [String] Formatted input display
       def input_display
-        return placeholder_display if @value.empty?
+        return placeholder_display if text_value.empty?
 
         value_with_cursor
       end
@@ -45,8 +49,9 @@ module Clack
       #
       # @return [String] Value with cursor
       def value_with_cursor
-        chars = @value.grapheme_clusters
-        return "#{@value}#{cursor_block}" if @cursor >= chars.length
+        val = text_value
+        chars = val.grapheme_clusters
+        return "#{val}#{cursor_block}" if @cursor >= chars.length
 
         before = chars[0...@cursor].join
         current = Colors.inverse(chars[@cursor])
@@ -55,7 +60,6 @@ module Clack
       end
 
       # Handle text input key (backspace/delete or printable character).
-      # Requires @value and @cursor instance variables.
       # Uses grapheme clusters for proper Unicode handling.
       #
       # @param key [String] The key pressed
@@ -64,21 +68,33 @@ module Clack
         return handle_backspace if Core::Settings.backspace?(key)
         return false unless Core::Settings.printable?(key)
 
-        chars = @value.grapheme_clusters
+        chars = text_value.grapheme_clusters
         chars.insert(@cursor, key)
-        @value = chars.join
+        self.text_value = chars.join
         @cursor += 1
         true
       end
 
+      # The text value being edited. Override to use a different backing store.
+      # @return [String]
+      def text_value
+        @value
+      end
+
+      # Set the text value. Override to use a different backing store.
+      # @param val [String]
+      def text_value=(val)
+        @value = val
+      end
+
       private
 
       def handle_backspace
         return false if @cursor.zero?
 
-        chars = @value.grapheme_clusters
+        chars = text_value.grapheme_clusters
         chars.delete_at(@cursor - 1)
-        @value = chars.join
+        self.text_value = chars.join
         @cursor -= 1
         true
       end

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

@@ -7,8 +7,8 @@ module Clack
     # Combines text input with a filtered option list. Type to filter,
     # use arrow keys to navigate matches, Enter to select.
     #
-    # By default, filtering searches across value, label, and hint fields
-    # using a case-insensitive substring match. Supply a custom +filter+
+    # 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
@@ -35,14 +35,15 @@ module Clack
     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 case-insensitive substring
-      #   match across label, value, and hint is used.
+      #   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, filter: nil, **opts)
         super(message:, **opts)
@@ -104,7 +105,7 @@ 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
@@ -136,37 +137,11 @@ module Clack
         @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
+          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]})") : ""