clack 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 671583e7a4d14fd6951369f179ed7ba6baf97c20fb54e202e08e710763448ee4
-  data.tar.gz: 28469575a56abce1883038147ac2ce5735b79cd976938d448b37227fe044f941
+  metadata.gz: 9b2beeffde4af3c88491d8b659dd781e8bd3e652e06f8c159a3ca7910fc69c87
+  data.tar.gz: 86b779a202099d27cf702009ee649e19a49b11305e10d2033cf7a0425fe38e10
 SHA512:
-  metadata.gz: 0a2d08f4e1eaf1434d7692666fb145ba6bd98c2f368193565a4ed0f4a23bf1b937b9909be4fd16541b7f26f7dc018b2f06b95215104c8121f0af964ea4487193
-  data.tar.gz: 879876e598e6213239b3aaf945e909587c02fa34fcbf2b971d816a41c21149fefbca1065aca5890e4cbb7148382b4a54262a21a2309dabcc5466cd4e43d13aea
+  metadata.gz: 9f8b20f670252b17132fcb664eeeaa3ba06b8a8fa0abbee5fdb8e40d17460f2e59badeda5b11b20aaa82b7e9b4b0fef6d06524933794dd20a3c6fcd159cc2115
+  data.tar.gz: 21642c6a8cea0671cff152932e806ea7a83163612ecd35739fa2e2bd98179b5e5b714ae6de3e5a2153206ac5f3b52f02ec2e28fc82541056a726d60071afbdab

data/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
-## [Unreleased]
+## [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
@@ -191,6 +208,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">
@@ -255,6 +284,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 +323,23 @@ 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
+
 ### Select Key
 
 Quick selection using keyboard shortcuts.
@@ -320,6 +373,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 +416,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 +456,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 +573,18 @@ 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)
+```
+
 ## 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!"

data/examples/demo.rb

@@ -0,0 +1,179 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo script showcasing all Clack Ruby prompts
+# Run with: ruby examples/demo.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+def run_demo
+  Clack.intro "clack-demo"
+
+  result = Clack.group(on_cancel: ->(_) { Clack.cancel("Operation cancelled.") }) do |g|
+    g.prompt(:name) do
+      Clack.text(
+        message: "What is your project named?",
+        placeholder: "my-app",
+        validate: ->(v) { "Project name is required" if v.to_s.strip.empty? }
+      )
+    end
+
+    g.prompt(:directory) do |r|
+      Clack.text(
+        message: "Where should we create your project?",
+        initial_value: "./#{r[:name]}"
+      )
+    end
+
+    g.prompt(:template) do
+      Clack.select(
+        message: "Which template would you like to use?",
+        options: [
+          {value: "default", label: "Default", hint: "recommended"},
+          {value: "minimal", label: "Minimal", hint: "bare bones"},
+          {value: "api", label: "API Only", hint: "no frontend"},
+          {value: "full", label: "Full Stack", hint: "everything included"}
+        ]
+      )
+    end
+
+    g.prompt(:typescript) do
+      Clack.confirm(
+        message: "Would you like to use TypeScript?",
+        initial_value: true
+      )
+    end
+
+    g.prompt(:features) do
+      Clack.multiselect(
+        message: "Which features would you like to include?",
+        options: [
+          {value: "eslint", label: "ESLint", hint: "code linting"},
+          {value: "prettier", label: "Prettier", hint: "code formatting"},
+          {value: "tailwind", label: "Tailwind CSS", hint: "utility-first CSS"},
+          {value: "docker", label: "Docker", hint: "containerization"},
+          {value: "ci", label: "GitHub Actions", hint: "CI/CD pipeline"}
+        ],
+        initial_values: %w[eslint prettier],
+        required: false
+      )
+    end
+
+    g.prompt(:package_manager) do
+      Clack.select(
+        message: "Which package manager do you prefer?",
+        options: [
+          {value: "npm", label: "npm"},
+          {value: "yarn", label: "yarn"},
+          {value: "pnpm", label: "pnpm", hint: "recommended"},
+          {value: "bun", label: "bun", hint: "fast"}
+        ],
+        initial_value: "pnpm"
+      )
+    end
+  end
+
+  return if Clack.handle_cancel(result)
+
+  # Autocomplete prompt
+  color = Clack.autocomplete(
+    message: "Pick a theme color:",
+    options: %w[red orange yellow green blue indigo violet pink cyan magenta]
+  )
+  return if Clack.handle_cancel(color)
+
+  # Select key prompt (quick keyboard shortcuts)
+  action = Clack.select_key(
+    message: "What would you like to do first?",
+    options: [
+      {value: "dev", label: "Start dev server", key: "d"},
+      {value: "build", label: "Build for production", key: "b"},
+      {value: "test", label: "Run tests", key: "t"}
+    ]
+  )
+  return if Clack.handle_cancel(action)
+
+  # Path prompt
+  config_path = Clack.path(
+    message: "Select config directory:",
+    only_directories: true
+  )
+  return if Clack.handle_cancel(config_path)
+
+  # Group multiselect
+  stack = Clack.group_multiselect(
+    message: "Select additional integrations:",
+    options: [
+      {
+        label: "Frontend",
+        options: [
+          {value: "react", label: "React"},
+          {value: "vue", label: "Vue"},
+          {value: "svelte", label: "Svelte"}
+        ]
+      },
+      {
+        label: "Backend",
+        options: [
+          {value: "express", label: "Express"},
+          {value: "fastify", label: "Fastify"},
+          {value: "hono", label: "Hono"}
+        ]
+      },
+      {
+        label: "Database",
+        options: [
+          {value: "postgres", label: "PostgreSQL"},
+          {value: "mysql", label: "MySQL"},
+          {value: "sqlite", label: "SQLite"}
+        ]
+      }
+    ],
+    required: false
+  )
+  return if Clack.handle_cancel(stack)
+
+  # Progress bar
+  prog = Clack.progress(total: 100, message: "Downloading assets...")
+  prog.start
+  20.times do
+    sleep 0.03
+    prog.advance(5)
+  end
+  prog.stop("Assets downloaded!")
+
+  # Tasks
+  Clack.tasks(tasks: [
+    {title: "Validating configuration", task: -> { sleep 0.3 }},
+    {title: "Generating types", task: -> { sleep 0.4 }},
+    {title: "Compiling assets", task: -> { sleep 0.3 }}
+  ])
+
+  # Spinner
+  s = Clack.spinner
+  s.start "Installing dependencies via #{result[:package_manager]}..."
+  sleep 1.0
+  s.message "Configuring #{result[:template]} template..."
+  sleep 0.6
+  s.stop "Project created successfully!"
+
+  # Summary
+  Clack.log.step "Project: #{result[:name]}"
+  Clack.log.step "Directory: #{result[:directory]}"
+  Clack.log.step "Template: #{result[:template]}"
+  Clack.log.step "TypeScript: #{result[:typescript] ? "Yes" : "No"}"
+  Clack.log.step "Features: #{result[:features].join(", ")}" unless result[:features].empty?
+  Clack.log.step "Color: #{color}"
+  Clack.log.step "Action: #{action}"
+  Clack.log.step "Config: #{config_path}"
+  Clack.log.step "Stack: #{stack.join(", ")}" unless stack.empty?
+
+  Clack.note <<~MSG, title: "Next steps"
+    cd #{result[:directory]}
+    #{result[:package_manager]} run dev
+  MSG
+
+  Clack.outro "Happy coding!"
+end
+
+run_demo if __FILE__ == $PROGRAM_NAME

data/examples/full_demo.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Full demo showcasing Clack Ruby features
+# Run with: ruby examples/full_demo.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "create-service"
+
+# Text input
+name = Clack.text(
+  message: "Service name:",
+  placeholder: "order-service"
+)
+exit 1 if Clack.handle_cancel(name)
+
+# Password input (masked)
+token = Clack.password(
+  message: "GitHub token:",
+  mask: "•"
+)
+exit 1 if Clack.handle_cancel(token)
+
+# Confirm
+use_openapi = Clack.confirm(
+  message: "Generate OpenAPI spec?",
+  initial_value: true
+)
+exit 1 if Clack.handle_cancel(use_openapi)
+
+# Select (single choice)
+language = Clack.select(
+  message: "Language:",
+  options: [
+    {value: "java", label: "Java 21", hint: "Spring Boot 3"},
+    {value: "python", label: "Python 3.12", hint: "FastAPI"},
+    {value: "go", label: "Go 1.22", hint: "chi"},
+    {value: "node", label: "Node.js 22", hint: "Fastify"}
+  ]
+)
+exit 1 if Clack.handle_cancel(language)
+
+# Multiselect
+integrations = Clack.multiselect(
+  message: "Integrations:",
+  options: [
+    {value: "postgres", label: "PostgreSQL"},
+    {value: "redis", label: "Redis"},
+    {value: "kafka", label: "Kafka"},
+    {value: "s3", label: "S3"}
+  ],
+  required: false
+)
+exit 1 if Clack.handle_cancel(integrations)
+
+# Progress bar
+prog = Clack.progress(total: 100, message: "Scaffolding...")
+prog.start
+5.times do
+  sleep 0.4
+  prog.advance(20)
+end
+prog.stop("Done")
+
+# Spinner
+s = Clack.spinner
+s.start "Installing dependencies..."
+sleep 0.8
+s.message "Configuring CI..."
+sleep 0.6
+s.stop "Ready"
+
+# Summary
+Clack.log.step "Service: #{name}"
+Clack.log.step "Stack: #{language}"
+Clack.log.step "Integrations: #{integrations.join(", ")}" unless integrations.empty?
+
+Clack.note <<~MSG, title: "Next steps"
+  cd #{name}
+  make dev
+MSG
+
+Clack.outro "Ship it"