clack 0.1.4 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 671583e7a4d14fd6951369f179ed7ba6baf97c20fb54e202e08e710763448ee4
-  data.tar.gz: 28469575a56abce1883038147ac2ce5735b79cd976938d448b37227fe044f941
+  metadata.gz: c0622f234b9f83906c6440e54c29a12715ecfc7a2b3777ec68efaf3882defcb7
+  data.tar.gz: 450c6376c40ad88a27683294e97292f227e2081ccc90a0c076949bba3e5afd1d
 SHA512:
-  metadata.gz: 0a2d08f4e1eaf1434d7692666fb145ba6bd98c2f368193565a4ed0f4a23bf1b937b9909be4fd16541b7f26f7dc018b2f06b95215104c8121f0af964ea4487193
-  data.tar.gz: 879876e598e6213239b3aaf945e909587c02fa34fcbf2b971d816a41c21149fefbca1065aca5890e4cbb7148382b4a54262a21a2309dabcc5466cd4e43d13aea
+  metadata.gz: '08a7d471122e503168817430b65ad3618488eef6a2c79229a50e20a0a3ff3f2df741faef330a81b57875ddca3a37a68d0aebd19e770b7bbe73addd9a737bc9ec'
+  data.tar.gz: 76e01f5eef142fd64069e1d9ba705edebc5694834ab68d5f7a8370eb345f1bf1473f2f1771d0178ed80e0b6c977c05d032d0059112bf36e72dd2fbe18f3850a3

data/CHANGELOG.md

@@ -1,6 +1,81 @@
 # Changelog
 
-## [Unreleased]
+## [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
+- `date` prompt for inline segmented date selection with Tab/arrow navigation and digit typing
+- Date min/max enforcement: clamps values to bounds during navigation
+- Date-specific validators: `Validators.future_date`, `Validators.past_date`, `Validators.date_range`
+- `autocomplete` now accepts `filter:` proc for custom matching logic
+- `tasks` now passes a message-update proc to task callbacks for mid-task status updates
+- `tasks` now supports `enabled:` flag to conditionally skip tasks
+- 100% YARD documentation coverage (was 79%)
+- 30 new edge-case tests covering warning validation, transforms, date boundaries, and more
+
+### Changed
+- `Transformers.resolve` now accepts any object responding to `#call` (not just Proc)
+- Standardized required-validation error messages across multiselect variants
+- Extracted `dispatch_key` from `handle_key` in base `Prompt` so warning/error state transitions are handled centrally for all prompts
+- Ruby idiom improvements: pattern matching, endless methods, guard clauses, `find_index`
+- Gemspec now excludes dev-only files (cast, exp, gif, svg) from the gem package
+- Examples include `require "clack"` alternative comment for gem users
+
+### Fixed
+- `Password#handle_input` now correctly handles backspace (was unreachable due to guard order)
+- `Validators.as_warning` no longer double-wraps values that are already `Warning` instances
+- `AutocompleteMultiselect` backspace was dead code (printable guard blocked it)
+- `MultilineText` and `Autocomplete` now render warning validation messages (was error-only)
+- Removed dead `@buffer` and `@name` instance variables from `TaskLogGroup`
 
 ## [0.1.4] - 2026-01-23
 

data/README.md

@@ -95,9 +95,16 @@ agg examples/demo.cast examples/demo.gif --font-size 18 --cols 80 --rows 28 --sp
 All prompts return the user's input, or `Clack::CANCEL` if they pressed Escape/Ctrl+C.
 
 ```ruby
-# Always check for cancellation
+# Check for cancellation
 result = Clack.text(message: "Name?")
 exit 1 if Clack.cancel?(result)
+
+# Or use handle_cancel for a one-liner that prints "Cancelled" and returns true
+result = Clack.text(message: "Name?")
+exit 1 if Clack.handle_cancel(result)
+
+# With a custom message
+exit 1 if Clack.handle_cancel(result, "Aborted by user")
 ```
 
 ### Validation & Transforms
@@ -144,15 +151,25 @@ Built-in validators and transformers:
 
 ```ruby
 # Validators - return error message, Warning, or nil
-Clack::Validators.required
-Clack::Validators.min_length(8)
+Clack::Validators.required              # Non-empty input
+Clack::Validators.min_length(3)         # Minimum character count
+Clack::Validators.max_length(100)       # Maximum character count
 Clack::Validators.format(/\A[a-z]+\z/, "Only lowercase")
-Clack::Validators.email
-Clack::Validators.combine(v1, v2)  # First error/warning wins
+Clack::Validators.email                 # Email format (user@host.tld)
+Clack::Validators.url                   # URL format (http/https)
+Clack::Validators.integer               # Integer string ("-5", "42")
+Clack::Validators.in_range(1..100)      # Numeric range (parses as int)
+Clack::Validators.one_of(%w[a b c])     # Allowlist check
+Clack::Validators.path_exists           # File/dir exists on disk
+Clack::Validators.directory_exists      # Directory exists on disk
+Clack::Validators.future_date           # Date strictly after today
+Clack::Validators.past_date             # Date strictly before today
+Clack::Validators.date_range(min: d1, max: d2) # Date within range
+Clack::Validators.combine(v1, v2)       # First error/warning wins
 
 # Warning validators - allow user to confirm or edit
-Clack::Validators.file_exists_warning  # For file overwrite confirmations
-Clack::Validators.as_warning(validator)  # Convert any validator to warning
+Clack::Validators.file_exists_warning   # For file overwrite confirmations
+Clack::Validators.as_warning(validator) # Convert any validator to warning
 
 # Transformers - normalize the value (use :symbol or Clack::Transformers.name)
 :strip / :trim      # Remove leading/trailing whitespace
@@ -176,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}*") }
 )
 ```
 
@@ -191,6 +225,18 @@ secret = Clack.password(
 )
 ```
 
+### Multiline Text
+
+Multi-line text input. Enter inserts a newline, Ctrl+D submits.
+
+```ruby
+bio = Clack.multiline_text(
+  message: "Tell us about yourself",
+  initial_value: "Hello!\n",
+  validate: ->(v) { "Too short" if v.strip.length < 10 }
+)
+```
+
 ### Confirm
 
 <img src="examples/images/confirm.svg" alt="Confirm prompt">
@@ -247,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(
@@ -255,6 +301,13 @@ color = Clack.autocomplete(
   options: %w[red orange yellow green blue indigo violet],
   placeholder: "Type to search..."
 )
+
+# Custom filter logic (receives option hash and query string)
+cmd = Clack.autocomplete(
+  message: "Select command",
+  options: commands,
+  filter: ->(opt, query) { opt[:label].start_with?(query) }
+)
 ```
 
 ### Autocomplete Multiselect
@@ -287,6 +340,37 @@ project_dir = Clack.path(
 
 **Navigation:** Type to filter | `Tab` to autocomplete | `↑↓` to select
 
+### Date
+
+Segmented date picker with three format modes.
+
+```ruby
+date = Clack.date(
+  message: "Release date?",
+  format: :us,                        # :iso (YYYY-MM-DD), :us (MM/DD/YYYY), :eu (DD/MM/YYYY)
+  initial_value: Date.today + 7,
+  min: Date.today,
+  max: Date.today + 365,
+  validate: ->(d) { "Not a Friday" unless d.friday? }
+)
+```
+
+**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.
@@ -320,6 +404,23 @@ spinner.stop("Dependencies installed!")
 # Or: spinner.cancel("Cancelled")
 ```
 
+**Block form** - wraps a block with automatic success/error handling:
+
+```ruby
+result = Clack.spin("Installing dependencies...") { system("npm install") }
+
+# With custom messages
+Clack.spin("Compiling...", success: "Build complete!") { build_project }
+
+# Access the spinner inside the block
+Clack.spin("Working...") do |s|
+  s.message "Step 1..."
+  do_step_1
+  s.message "Step 2..."
+  do_step_2
+end
+```
+
 ### Progress
 
 Visual progress bar for measurable operations.
@@ -346,6 +447,22 @@ results = Clack.tasks(tasks: [
   { title: "Building project", task: -> { build } },
   { title: "Running tests", task: -> { run_tests } }
 ])
+
+# Update the spinner message mid-task
+Clack.tasks(tasks: [
+  { title: "Installing", task: ->(message) {
+    message.call("Fetching packages...")
+    fetch_packages
+    message.call("Compiling...")
+    compile
+  }}
+])
+
+# Conditionally skip tasks with enabled:
+Clack.tasks(tasks: [
+  { title: "Lint", task: -> { lint } },
+  { title: "Deploy", task: -> { deploy }, enabled: ENV["DEPLOY"] == "true" }
+])
 ```
 
 ### Group Multiselect
@@ -370,7 +487,9 @@ features = Clack.group_multiselect(
         { value: "solid_queue", label: "Solid Queue" }
       ]
     }
-  ]
+  ],
+  selectable_groups: true,  # Toggle all options in a group at once
+  group_spacing: 1          # Blank lines between groups
 )
 ```
 
@@ -485,6 +604,61 @@ Clack.outro("Done!")        # └ Done!
 Clack.cancel("Aborted")     # └ Aborted (red)
 ```
 
+## Configuration
+
+Customize key bindings and display options globally:
+
+```ruby
+# Add custom key bindings (merged with defaults)
+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/examples/advanced_prompts.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demonstrates advanced prompt types: multiline_text, path, select_key, autocomplete
+# Run with: ruby examples/advanced_prompts.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "advanced-prompts"
+
+# Multi-line text with initial value (Ctrl+D to submit)
+description = Clack.multiline_text(
+  message: "Project description:",
+  initial_value: "A Ruby CLI tool that "
+)
+exit 0 if Clack.cancel?(description)
+
+Clack.log.info "Description:\n#{description}"
+
+# Path selector (directories only, rooted at home)
+project_dir = Clack.path(
+  message: "Choose project directory:",
+  root: Dir.home,
+  only_directories: true
+)
+exit 0 if Clack.cancel?(project_dir)
+
+Clack.log.info "Directory: #{project_dir}"
+
+# Select by key press (instant selection)
+action = Clack.select_key(
+  message: "What next?",
+  options: [
+    {value: "init", label: "Initialize repo", key: "i", hint: "git init"},
+    {value: "clone", label: "Clone existing", key: "c", hint: "git clone"},
+    {value: "open", label: "Open in editor", key: "o"},
+    {value: "skip", label: "Skip", key: "s"}
+  ]
+)
+exit 0 if Clack.cancel?(action)
+
+Clack.log.step "Action: #{action}"
+
+# Autocomplete with placeholder
+license = Clack.autocomplete(
+  message: "Pick a license:",
+  placeholder: "Type to search...",
+  options: [
+    {value: "mit", label: "MIT", hint: "permissive"},
+    {value: "apache2", label: "Apache 2.0", hint: "permissive"},
+    {value: "gpl3", label: "GPL 3.0", hint: "copyleft"},
+    {value: "agpl3", label: "AGPL 3.0", hint: "copyleft"},
+    {value: "bsd2", label: "BSD 2-Clause", hint: "permissive"},
+    {value: "bsd3", label: "BSD 3-Clause", hint: "permissive"},
+    {value: "mpl2", label: "MPL 2.0", hint: "weak copyleft"},
+    {value: "unlicense", label: "Unlicense", hint: "public domain"}
+  ]
+)
+exit 0 if Clack.cancel?(license)
+
+Clack.log.success "License: #{license}"
+
+Clack.outro "Done!"

data/examples/basic.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/basic.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "basic-example"
+
+name = Clack.text(message: "What is your name?", placeholder: "Anonymous")
+exit 0 if Clack.cancel?(name)
+
+Clack.log.success "Hello, #{name}!"
+
+Clack.outro "Goodbye!"

data/examples/create_app.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/create_app.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "create-my-app"
+
+# Project name
+name = Clack.text(
+  message: "Project name?",
+  placeholder: "my-app",
+  validate: ->(v) { "Project name is required" if v.to_s.strip.empty? }
+)
+exit 0 if Clack.cancel?(name)
+
+# Framework selection
+framework = Clack.select(
+  message: "Pick a framework",
+  options: [
+    {value: "rails", label: "Ruby on Rails", hint: "full-stack"},
+    {value: "sinatra", label: "Sinatra", hint: "micro"},
+    {value: "hanami", label: "Hanami"},
+    {value: "roda", label: "Roda"}
+  ]
+)
+exit 0 if Clack.cancel?(framework)
+
+# Feature selection
+features = Clack.multiselect(
+  message: "Select features",
+  options: [
+    {value: "api", label: "API Mode"},
+    {value: "auth", label: "Authentication"},
+    {value: "admin", label: "Admin Panel"},
+    {value: "docker", label: "Docker Setup"},
+    {value: "ci", label: "GitHub Actions CI"}
+  ],
+  required: false
+)
+exit 0 if Clack.cancel?(features)
+
+# Database
+database = Clack.select(
+  message: "Select database",
+  options: [
+    {value: "postgresql", label: "PostgreSQL", hint: "recommended"},
+    {value: "mysql", label: "MySQL"},
+    {value: "sqlite", label: "SQLite"}
+  ]
+)
+exit 0 if Clack.cancel?(database)
+
+# Confirm
+proceed = Clack.confirm(message: "Create project?")
+exit 0 if Clack.cancel?(proceed)
+
+unless proceed
+  Clack.outro "Project creation cancelled."
+  exit 0
+end
+
+# Simulate installation
+s = Clack.spinner
+s.start "Creating project..."
+sleep 1
+s.message "Installing dependencies..."
+sleep 1
+s.message "Configuring #{framework}..."
+sleep 0.5
+s.stop "Project created!"
+
+# Summary
+Clack.log.info "Project: #{name}"
+Clack.log.success "Framework: #{framework}"
+Clack.log.step "Database: #{database}"
+Clack.log.step "Features: #{features.join(", ")}" unless features.empty?
+
+Clack.note <<~NOTE, title: "Next Steps"
+  cd #{name}
+  bundle install
+  bin/rails server
+NOTE
+
+Clack.outro "Happy coding!"

data/examples/date_demo.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/date_demo.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "date-picker-demo"
+
+# Basic date selection
+date = Clack.date(
+  message: "When should this deploy?",
+  help: "Use Tab/arrows to navigate, Up/Down to adjust, or type digits"
+)
+exit 0 if Clack.cancel?(date)
+
+Clack.log.info "Selected: #{date}"
+
+# Date with bounds
+bounded_date = Clack.date(
+  message: "Pick a date this year",
+  format: :us,
+  initial_value: Date.today,
+  min: Date.new(Date.today.year, 1, 1),
+  max: Date.new(Date.today.year, 12, 31)
+)
+exit 0 if Clack.cancel?(bounded_date)
+
+Clack.log.info "Bounded date: #{bounded_date}"
+
+# Date with custom validation
+future_date = Clack.date(
+  message: "Schedule for future date",
+  validate: Clack::Validators.future_date
+)
+exit 0 if Clack.cancel?(future_date)
+
+Clack.log.success "Scheduled for #{future_date}"
+
+Clack.outro "Done!"