clack 0.4.4 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5a8d3270e58cb1ad88664e73215c2ea5217211829680707d7616714ba93c926
-  data.tar.gz: c8f58966b18a015c26b7669ebd495c0e7ba75d830088ad3135a0971dd03bc874
+  metadata.gz: e27f6e6ab9835d2855570ebdcd9b74a581becaffad5ba6a814e54ec5d44097b2
+  data.tar.gz: 8788e05802f917a1a6abe06697a4ca47ff451da0235d7336b560adf8558451a0
 SHA512:
-  metadata.gz: f3dbfd192f557ee0cd476be3ed80f54a57273e786d9120e3372c85527582ad8a30994b4202c83c309135383e6bedaaf275e756961912420961c09a24e53576e2
-  data.tar.gz: a692229800f14a3160aee3eca80f6c12b296c288e27dbf57b307b509090fdf0c72ca4e3712213f9515427ed0a48c70ee73534f85db887bb02ea1bfb9f0cf0177
+  metadata.gz: 173ead18da184ea230092d263bb4e607eb623c788fcdfae7d4315afbebe140bbe5335e42fa7c7ee460481916e46a6fda464f9b13f8d011228648dcf13a799704
+  data.tar.gz: 56fd6c8cbca6c610cb73941f565c84e62c6bcc38d5b48741c35c52b86c14e45ff858219e5973669d1db7beb4bb045259d11daa60d172d3e2603ad16c04e2e812

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.4.6] - 2026-03-22
+
+### Fixed
+- `Settings.printable?` now accepts combining characters and multi-codepoint grapheme clusters (accented letters, emoji)
+- Signal handlers use `write_nonblock` instead of `print` for async safety
+- `S_STEP_ERROR` ASCII fallback changed from `x` to `!` (was identical to `S_STEP_CANCEL`)
+- CI mode validation warnings now print to stderr instead of stdout
+
+### Changed
+- Colors, Cursor, and Symbols ANSI detection unified through `Environment.colors_supported?`
+- Extracted `build_final_frame` template into `Core::Prompt` with `final_display` hook (11 prompt classes simplified)
+- Date prompt: consolidated duplicated segment logic into `update_segment`
+
+## [0.4.5] - 2026-02-22
+
+### Fixed
+- `Autocomplete` and `AutocompleteMultiselect` now route all printable characters to the search field first, fixing vim aliases (`j`/`k`/`h`/`l`) hijacking text input
+- `AutocompleteMultiselect` no longer intercepts `a`/`i` keys as shortcuts — they conflicted with typing in the search field
+- `AutocompleteMultiselect#toggle_current` now respects `:disabled` options, matching `Multiselect` behavior
+
+### Changed
+- `AutocompleteMultiselect` internals aligned with `Multiselect`: `@selected` naming, `submit` override pattern, `keyboard_hints` method, `build_frame` validation rendering, `initial_values: []` default
+
+### Added
+- `examples/showcase.rb` — full-featured demo with branching, autocomplete, date, range, group multiselect, tasks
+- `examples/migration_from_tty_prompt.rb` — side-by-side migration guide from tty-prompt
+- README: "Why Clack?" comparison table vs tty-prompt/highline, quick reference table, TL;DR tagline, vim key notes on autocomplete sections
+
 ## [0.4.4] - 2026-02-21
 
 ### Fixed

data/README.md

@@ -2,7 +2,7 @@
 
 **Effortlessly beautiful CLI prompts for Ruby.**
 
-A faithful Ruby port of [@clack/prompts](https://github.com/bombshell-dev/clack).
+A faithful Ruby port of [@clack/prompts](https://github.com/bombshell-dev/clack). 16+ prompt types, zero dependencies, Ruby 3.2+. `gem "clack"` and go.
 
 <p align="center">
   <img src="examples/demo.gif?v=2" width="640" alt="Clack demo">
@@ -10,10 +10,11 @@ A faithful Ruby port of [@clack/prompts](https://github.com/bombshell-dev/clack)
 
 ## Why Clack?
 
-- **Beautiful by default** - Thoughtfully designed prompts that just look right
-- **Vim-friendly** - Navigate with `hjkl` or arrow keys
-- **Accessible** - Graceful ASCII fallbacks for limited terminals
-- **Composable** - Group prompts together with `Clack.group`
+- **Beautiful by default** — Thoughtfully designed prompts that just look right
+- **Vim-friendly** — Navigate with `hjkl` or arrow keys
+- **Accessible** — Graceful ASCII fallbacks for limited terminals
+- **Composable** — Group prompts together with `Clack.group`
+- **Zero dependencies** — Everything in one gem
 
 ## Installation
 
@@ -299,7 +300,8 @@ Type to filter from a list of options. Filtering uses **fuzzy matching** by defa
 color = Clack.autocomplete(
   message: "Pick a color",
   options: %w[red orange yellow green blue indigo violet],
-  placeholder: "Type to search..."
+  placeholder: "Type to search...",
+  max_items: 5  # Default; scrollable via ↑↓
 )
 
 # Custom filter logic (receives option hash and query string)
@@ -310,6 +312,8 @@ cmd = Clack.autocomplete(
 )
 ```
 
+> Vim-style `j`/`k`/`h`/`l` navigation is not available — all keyboard input feeds into the search field. Use `↑↓` arrow keys to navigate results.
+
 ### Autocomplete Multiselect
 
 Type to filter with multi-selection support.
@@ -320,11 +324,14 @@ colors = Clack.autocomplete_multiselect(
   options: %w[red orange yellow green blue indigo violet],
   placeholder: "Type to filter...",
   required: true,              # At least one selection required
-  initial_values: ["red"]      # Pre-selected values
+  initial_values: ["red"],     # Pre-selected values
+  max_items: 5                 # Default; scrollable via ↑↓
 )
 ```
 
-**Shortcuts:** `Space` toggle | `a` toggle all | `i` invert | `Enter` confirm
+**Shortcuts:** `Space` toggle | `Enter` confirm
+
+> The `a` (select all), `i` (invert), and `j`/`k`/`h`/`l` shortcuts from `Multiselect` are not available here — all keyboard input feeds into the search field instead. Use `↑↓` arrow keys to navigate.
 
 ### Path
 
@@ -493,6 +500,32 @@ features = Clack.group_multiselect(
 )
 ```
 
+<details>
+<summary><h3 style="display:inline">Quick Reference</h3></summary>
+
+| Prompt | Method | Key Options | Defaults |
+|--------|--------|-------------|----------|
+| Text | `Clack.text` | `placeholder:`, `default_value:`, `initial_value:`, `completions:` | — |
+| Password | `Clack.password` | `mask:`, `validate:` | `mask: "▪"` |
+| Confirm | `Clack.confirm` | `active:`, `inactive:`, `initial_value:` | `active: "Yes"`, `inactive: "No"`, `initial_value: true` |
+| Select | `Clack.select` | `options:`, `initial_value:`, `max_items:` | — |
+| Multiselect | `Clack.multiselect` | `options:`, `initial_values:`, `required:`, `cursor_at:` | `required: true` |
+| Group Multiselect | `Clack.group_multiselect` | `options:` (nested), `selectable_groups:`, `group_spacing:` | `selectable_groups: false` |
+| Autocomplete | `Clack.autocomplete` | `options:`, `placeholder:`, `filter:`, `max_items:` | `max_items: 5` |
+| Autocomplete Multiselect | `Clack.autocomplete_multiselect` | `options:`, `required:`, `initial_values:`, `filter:` | `required: true`, `max_items: 5` |
+| Select Key | `Clack.select_key` | `options:` (with `:key`) | — |
+| Path | `Clack.path` | `root:`, `only_directories:` | `root: "."` |
+| Date | `Clack.date` | `format:`, `initial_value:`, `min:`, `max:` | `format: :iso` |
+| Range | `Clack.range` | `min:`, `max:`, `step:`, `initial_value:` | `min: 0`, `max: 100`, `step: 1` |
+| Multiline Text | `Clack.multiline_text` | `initial_value:`, `validate:` | Submit with **Ctrl+D** |
+| Spinner | `Clack.spinner` / `Clack.spin` | block form auto-handles success/error | — |
+| Tasks | `Clack.tasks` | `tasks:` (`{title:, task:, enabled:}`) | `enabled: true` |
+| Progress | `Clack.progress` | `total:`, `message:` | — |
+
+All prompts accept `message:`, `validate:`, `help:`, and return `Clack::CANCEL` on Escape/Ctrl+C.
+
+</details>
+
 ## Prompt Groups
 
 Chain multiple prompts and collect results in a hash. Cancellation is handled automatically.
@@ -673,6 +706,10 @@ bundle exec rake spec   # Tests only
 COVERAGE=true bundle exec rake spec  # With coverage
 ```
 
+## Roadmap
+
+- **Wizard mode** - Multi-step flows with back navigation (`Clack.wizard`). The current `Clack.group` runs prompts as sequential Ruby code, so there's no way to "go back" and re-answer a previous question. A declarative wizard API would define steps as a graph with branching and let the engine handle forward/back navigation.
+
 ## Credits
 
 This is a Ruby port of [Clack](https://github.com/bombshell-dev/clack), created by [Nate Moore](https://github.com/natemoo-re) and the [Astro](https://astro.build) team.

data/examples/migration_from_tty_prompt.rb

@@ -0,0 +1,218 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Migration Guide: tty-prompt -> Clack
+#
+# This file shows common tty-prompt patterns and their Clack equivalents.
+# Each section shows the tty-prompt code (commented out) followed by
+# runnable Clack code that does the same thing.
+#
+# Run with: ruby examples/migration_from_tty_prompt.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "Migrating from tty-prompt to Clack"
+
+# ─────────────────────────────────────────────
+# 1. Basic text input
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   prompt = TTY::Prompt.new
+#   name = prompt.ask("What is your name?", default: "World")
+#
+# Clack equivalent:
+
+name = Clack.text(
+  message: "What is your name?",
+  placeholder: "World",
+  default_value: "World"
+)
+exit 0 if Clack.cancel?(name)
+
+Clack.log.info "Name: #{name}"
+
+# ─────────────────────────────────────────────
+# 2. Password input
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   secret = prompt.mask("Enter your API key:")
+#
+# Clack equivalent:
+
+secret = Clack.password(message: "Enter your API key:")
+exit 0 if Clack.cancel?(secret)
+
+Clack.log.info "Key entered (#{secret.length} chars)"
+
+# ─────────────────────────────────────────────
+# 3. Yes/No confirmation
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   prompt.yes?("Continue setup?")            # => true/false
+#   prompt.no?("Skip optional steps?")        # => true/false (inverted default)
+#
+# Clack equivalent:
+#   Use initial_value: false to mimic prompt.no? (default to "No")
+
+continue = Clack.confirm(message: "Continue setup?")
+exit 0 if Clack.cancel?(continue)
+
+Clack.log.info "Continue: #{continue}"
+
+# ─────────────────────────────────────────────
+# 4. Single select
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   color = prompt.select("Pick a color", %w[Red Green Blue])
+#
+#   # or with values:
+#   color = prompt.select("Pick a color") do |menu|
+#     menu.choice "Red",   :red
+#     menu.choice "Green", :green
+#     menu.choice "Blue",  :blue
+#   end
+#
+# Clack equivalent:
+
+color = Clack.select(
+  message: "Pick a color",
+  options: [
+    {value: :red, label: "Red"},
+    {value: :green, label: "Green"},
+    {value: :blue, label: "Blue"}
+  ]
+)
+exit 0 if Clack.cancel?(color)
+
+Clack.log.info "Color: #{color}"
+
+# ─────────────────────────────────────────────
+# 5. Multi-select
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   toppings = prompt.multi_select("Choose toppings") do |menu|
+#     menu.choice "Cheese",     :cheese
+#     menu.choice "Pepperoni",  :pepperoni
+#     menu.choice "Mushrooms",  :mushrooms
+#     menu.choice "Olives",     :olives
+#   end
+#
+# Clack equivalent:
+
+toppings = Clack.multiselect(
+  message: "Choose toppings",
+  options: [
+    {value: :cheese, label: "Cheese"},
+    {value: :pepperoni, label: "Pepperoni"},
+    {value: :mushrooms, label: "Mushrooms"},
+    {value: :olives, label: "Olives"}
+  ],
+  required: false
+)
+exit 0 if Clack.cancel?(toppings)
+
+Clack.log.info "Toppings: #{toppings.join(", ")}"
+
+# ─────────────────────────────────────────────
+# 6. Autocomplete / filtering
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   lang = prompt.select("Pick a language", %w[Ruby Python JavaScript Go Rust], filter: true)
+#
+# Clack has a dedicated autocomplete prompt with built-in fuzzy matching:
+
+lang = Clack.autocomplete(
+  message: "Pick a language (type to filter)",
+  options: [
+    {value: "ruby", label: "Ruby"},
+    {value: "python", label: "Python"},
+    {value: "javascript", label: "JavaScript"},
+    {value: "go", label: "Go"},
+    {value: "rust", label: "Rust"}
+  ]
+)
+exit 0 if Clack.cancel?(lang)
+
+Clack.log.info "Language: #{lang}"
+
+# ─────────────────────────────────────────────
+# 7. Validation
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   email = prompt.ask("Email?", validate: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\z/i)
+#   age   = prompt.ask("Age?") { |q| q.validate(->(v) { v.to_i > 0 }, "Must be positive") }
+#
+# Clack uses a validate lambda that returns nil (pass) or an error string:
+
+email = Clack.text(
+  message: "Email?",
+  validate: ->(v) {
+    "Invalid email" unless v.match?(/\A[\w+\-.]+@[a-z\d-]+(\.[a-z]+)*\z/i)
+  }
+)
+exit 0 if Clack.cancel?(email)
+
+Clack.log.info "Email: #{email}"
+
+# ─────────────────────────────────────────────
+# 8. Collecting multiple prompts (group)
+# ─────────────────────────────────────────────
+#
+# tty-prompt:
+#   result = prompt.collect do
+#     key(:name).ask("Name?")
+#     key(:role).select("Role?", %w[Admin User Guest])
+#     key(:notify).yes?("Send welcome email?")
+#   end
+#   # => { name: "Alice", role: "User", notify: true }
+#
+# Clack.group collects answers into a hash and handles cancellation:
+
+result = Clack.group(
+  on_cancel: ->(_partial) {
+    Clack.cancel "Setup cancelled"
+    exit 0
+  }
+) do |g|
+  g.prompt(:name) { Clack.text(message: "Name?", placeholder: "Alice") }
+
+  g.prompt(:role) do
+    Clack.select(
+      message: "Role?",
+      options: %w[Admin User Guest].map { |r| {value: r.downcase, label: r} }
+    )
+  end
+
+  g.prompt(:notify) { Clack.confirm(message: "Send welcome email?") }
+end
+
+Clack.log.info "Name: #{result[:name]}"
+Clack.log.info "Role: #{result[:role]}"
+Clack.log.info "Notify: #{result[:notify]}"
+
+# ─────────────────────────────────────────────
+# Quick reference
+# ─────────────────────────────────────────────
+
+Clack.note <<~TABLE, title: "Quick Reference"
+  tty-prompt              Clack
+  ─────────────────────   ──────────────────────────────
+  prompt.ask              Clack.text
+  prompt.mask             Clack.password
+  prompt.yes? / prompt.no?  Clack.confirm
+  prompt.select           Clack.select
+  prompt.multi_select     Clack.multiselect
+  prompt.select(filter:)  Clack.autocomplete
+  prompt.collect          Clack.group
+  prompt.say / prompt.warn  Clack.log.info / .warning
+  TTY::Spinner            Clack.spinner / Clack.spin
+TABLE
+
+Clack.outro "Migration complete! See the README for the full API."

data/examples/showcase.rb

@@ -0,0 +1,224 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Ultimate Clack showcase — every impressive feature in one flow.
+# Run with: ruby -Ilib examples/showcase.rb
+
+require "clack"
+
+Clack.intro "deploy-wizard"
+
+# --- Text with tab completions ---
+project = Clack.text(
+  message: "Project name:",
+  placeholder: "my-app",
+  completions: %w[acme-api acme-web acme-admin acme-workers billing-service payment-gateway
+    notification-hub auth-proxy data-pipeline analytics-engine search-indexer
+    cdn-edge config-server feature-flags rate-limiter],
+  validate: ->(v) { "Name is required" if v.to_s.strip.empty? }
+)
+exit 0 if Clack.cancel?(project)
+
+# --- Autocomplete with fuzzy search (big list) ---
+stack = Clack.autocomplete(
+  message: "Tech stack:",
+  placeholder: "Type to search...",
+  options: [
+    {value: "rails", label: "Ruby on Rails", hint: "full-stack, batteries included"},
+    {value: "sinatra", label: "Sinatra", hint: "micro, DSL-style"},
+    {value: "hanami", label: "Hanami", hint: "clean architecture"},
+    {value: "roda", label: "Roda", hint: "routing tree"},
+    {value: "grape", label: "Grape", hint: "API framework"},
+    {value: "nextjs", label: "Next.js", hint: "React SSR"},
+    {value: "nuxt", label: "Nuxt", hint: "Vue SSR"},
+    {value: "sveltekit", label: "SvelteKit", hint: "Svelte SSR"},
+    {value: "phoenix", label: "Phoenix", hint: "Elixir"},
+    {value: "django", label: "Django", hint: "Python full-stack"},
+    {value: "fastapi", label: "FastAPI", hint: "Python async"},
+    {value: "express", label: "Express.js", hint: "Node.js minimal"},
+    {value: "fastify", label: "Fastify", hint: "Node.js fast"},
+    {value: "gin", label: "Gin", hint: "Go HTTP"},
+    {value: "actix", label: "Actix Web", hint: "Rust async"},
+    {value: "spring", label: "Spring Boot", hint: "Java enterprise"},
+    {value: "laravel", label: "Laravel", hint: "PHP full-stack"}
+  ]
+)
+exit 0 if Clack.cancel?(stack)
+
+# --- Branching: choice determines follow-up ---
+deploy_target = Clack.select(
+  message: "Deploy target:",
+  options: [
+    {value: "kubernetes", label: "Kubernetes", hint: "container orchestration"},
+    {value: "serverless", label: "Serverless", hint: "Lambda / Cloud Functions"},
+    {value: "bare_metal", label: "Bare Metal", hint: "traditional VPS"}
+  ]
+)
+exit 0 if Clack.cancel?(deploy_target)
+
+cloud = nil
+replicas = nil
+
+case deploy_target
+when "kubernetes"
+  cloud = Clack.select(
+    message: "Cloud provider:",
+    options: [
+      {value: "aws", label: "AWS EKS", hint: "Amazon"},
+      {value: "gcp", label: "GCP GKE", hint: "Google"},
+      {value: "azure", label: "Azure AKS", hint: "Microsoft"},
+      {value: "do", label: "DigitalOcean DOKS"}
+    ]
+  )
+  exit 0 if Clack.cancel?(cloud)
+
+  replicas = Clack.range(
+    message: "Pod replicas:",
+    min: 1,
+    max: 20,
+    step: 1,
+    initial_value: 3
+  )
+  exit 0 if Clack.cancel?(replicas)
+
+when "serverless"
+  cloud = Clack.select_key(
+    message: "Serverless platform:",
+    options: [
+      {value: "lambda", label: "AWS Lambda", key: "a"},
+      {value: "cloud_functions", label: "GCP Cloud Functions", key: "g"},
+      {value: "azure_functions", label: "Azure Functions", key: "z"},
+      {value: "cloudflare", label: "Cloudflare Workers", key: "c"}
+    ]
+  )
+  exit 0 if Clack.cancel?(cloud)
+  replicas = "auto"
+
+when "bare_metal"
+  cloud = "self-hosted"
+  replicas = Clack.range(
+    message: "Server count:",
+    min: 1,
+    max: 50,
+    step: 1,
+    initial_value: 2
+  )
+  exit 0 if Clack.cancel?(replicas)
+end
+
+# --- Group multiselect ---
+addons = Clack.group_multiselect(
+  message: "Add-ons:",
+  selectable_groups: true,
+  group_spacing: 1,
+  options: [
+    {
+      label: "Observability",
+      options: [
+        {value: "prometheus", label: "Prometheus + Grafana"},
+        {value: "datadog", label: "Datadog"},
+        {value: "sentry", label: "Sentry", hint: "error tracking"}
+      ]
+    },
+    {
+      label: "Data",
+      options: [
+        {value: "postgres", label: "PostgreSQL"},
+        {value: "redis", label: "Redis"},
+        {value: "elasticsearch", label: "Elasticsearch"},
+        {value: "kafka", label: "Kafka", hint: "event streaming"}
+      ]
+    },
+    {
+      label: "Security",
+      options: [
+        {value: "vault", label: "HashiCorp Vault", hint: "secrets"},
+        {value: "oauth", label: "OAuth2 / OIDC"},
+        {value: "waf", label: "WAF", hint: "web application firewall"}
+      ]
+    }
+  ],
+  required: false
+)
+exit 0 if Clack.cancel?(addons)
+
+# --- Autocomplete multiselect ---
+team = Clack.autocomplete_multiselect(
+  message: "Notify team members:",
+  options: [
+    {value: "alice", label: "Alice Chen", hint: "backend"},
+    {value: "bob", label: "Bob Martinez", hint: "frontend"},
+    {value: "carol", label: "Carol Kim", hint: "SRE"},
+    {value: "dave", label: "Dave Patel", hint: "security"},
+    {value: "eve", label: "Eve Johansson", hint: "PM"},
+    {value: "frank", label: "Frank Okafor", hint: "QA"},
+    {value: "grace", label: "Grace Liu", hint: "data"},
+    {value: "hank", label: "Hank Müller", hint: "DevOps"}
+  ],
+  required: false
+)
+exit 0 if Clack.cancel?(team)
+
+# --- Date picker ---
+deploy_date = Clack.date(
+  message: "Target deploy date:",
+  initial_value: Date.today + 7
+)
+exit 0 if Clack.cancel?(deploy_date)
+
+# --- Confirm ---
+go_live = Clack.confirm(
+  message: "Schedule deployment?",
+  initial_value: true
+)
+exit 0 if Clack.cancel?(go_live)
+
+unless go_live
+  Clack.outro "Deployment cancelled."
+  exit 0
+end
+
+# --- Tasks with mid-task message updates ---
+Clack.tasks(tasks: [
+  {title: "Validating configuration", task: -> {
+    sleep 0.6
+  }},
+  {title: "Provisioning infrastructure", task: ->(msg) {
+    msg.call("Creating #{deploy_target} cluster...")
+    sleep 0.8
+    msg.call("Configuring networking...")
+    sleep 0.5
+    msg.call("Setting up DNS...")
+    sleep 0.4
+  }},
+  {title: "Deploying #{project}", task: ->(msg) {
+    msg.call("Building container image...")
+    sleep 0.7
+    msg.call("Pushing to registry...")
+    sleep 0.5
+    msg.call("Rolling out #{replicas} replicas...")
+    sleep 0.6
+  }},
+  {title: "Running health checks", task: -> {
+    sleep 0.8
+  }}
+])
+
+# --- Summary ---
+Clack.log.success "Deployment scheduled!"
+Clack.log.step "Project: #{project}"
+Clack.log.step "Stack: #{stack}"
+Clack.log.step "Target: #{deploy_target} (#{cloud})"
+Clack.log.step "Replicas: #{replicas}"
+Clack.log.step "Add-ons: #{addons.join(", ")}" unless addons.empty?
+Clack.log.step "Team: #{team.join(", ")}" unless team.empty?
+Clack.log.step "Deploy date: #{deploy_date}"
+
+Clack.note <<~MSG, title: "What happens next"
+  1. CI pipeline will run at #{deploy_date}
+  2. Canary deploy to 10% traffic
+  3. Full rollout after 30min soak
+  4. Team notified via Slack
+MSG
+
+Clack.outro "Happy shipping!"

data/lib/clack/colors.rb

@@ -8,12 +8,7 @@ module Clack
   # - FORCE_COLOR environment variable forces colors on
   module Colors
     class << self
-      def enabled?
-        return true if ENV["FORCE_COLOR"] && ENV["FORCE_COLOR"] != "0"
-        return false if ENV["NO_COLOR"]
-
-        $stdout.tty?
-      end
+      def enabled? = Environment.colors_supported?
 
       # @!group Foreground Colors (standard)
 

data/lib/clack/core/cursor.rb

@@ -13,9 +13,7 @@ module Clack
         def enabled?
           return @enabled unless @enabled.nil?
 
-          # Default: check if output supports ANSI escape sequences
-          return true if ENV["FORCE_COLOR"] && ENV["FORCE_COLOR"] != "0"
-          $stdout.tty? && ENV["TERM"] != "dumb" && !ENV["NO_COLOR"]
+          Environment.colors_supported?
         end
 
         # Visibility

data/lib/clack/core/prompt.rb

@@ -316,13 +316,23 @@ module Clack
       end
 
       # Build the final frame shown after interaction ends.
-      # Override to show a different view for completed prompts.
+      # Default renders a one-line summary: bar, symbol+message, styled final value.
+      # Override {#final_display} to customize what value is shown.
+      # Override this entirely for multi-line final output (e.g. MultilineText).
       #
       # @return [String] the final frame content
       def build_final_frame
-        build_frame
+        "#{bar}\n" \
+          "#{symbol_for_state}  #{@message}\n" \
+          "#{bar}  #{styled_final_display}\n"
       end
 
+      # The text to display in the final frame after submit/cancel.
+      # Override in subclasses to customize (e.g. masked password, formatted date).
+      #
+      # @return [String]
+      def final_display = @value.to_s
+
       # Check if prompt has reached a terminal state.
       #
       # @return [Boolean] true if state is :submit or :cancel
@@ -337,13 +347,18 @@ module Clack
       def run_ci_mode
         submit
         if @state == :error
-          @output.print "#{Colors.yellow("!")}  #{Colors.yellow("CI mode: validation failed for")} \"#{@message}\": #{@error_message}\n"
+          $stderr.print "#{Colors.yellow("!")}  #{Colors.yellow("CI mode: validation failed for")} \"#{@message}\": #{@error_message}\n"
         end
         @value
       end
 
       private
 
+      def styled_final_display
+        text = final_display
+        (@state == :cancel) ? Colors.strikethrough(Colors.dim(text)) : Colors.dim(text)
+      end
+
       def warn_narrow_terminal
         return unless Environment.tty?(@output)
 

data/lib/clack/core/settings.rb

@@ -91,9 +91,9 @@ module Clack
           aliases[key] if ACTIONS.include?(aliases[key])
         end
 
-        # Check if a key is a printable character
+        # Check if a key is a printable character (handles combining marks and multi-codepoint grapheme clusters)
         def printable?(key)
-          key && key.length == 1 && key.ord >= PRINTABLE_CHAR_MIN
+          key && key.grapheme_clusters.length == 1 && key.ord >= PRINTABLE_CHAR_MIN
         end
 
         # Check if a key is a backspace/delete

data/lib/clack/prompts/autocomplete.rb

@@ -63,19 +63,21 @@ module Clack
       def handle_key(key)
         return if terminal_state?
 
+        # Printable characters always feed the search field.
+        # This prevents vim aliases (j/k/h/l) from hijacking text input.
+        if Core::Settings.printable?(key)
+          handle_text_input(key)
+          return
+        end
+
         action = Core::Settings.action?(key)
 
         case action
-        when :cancel
-          @state = :cancel
-        when :enter
-          submit_selection
-        when :up
-          move_selection(-1)
-        when :down
-          move_selection(1)
-        else
-          handle_text_input(key)
+        when :cancel then @state = :cancel
+        when :enter then submit_selection
+        when :up then move_selection(-1)
+        when :down then move_selection(1)
+        else handle_text_input(key)
         end
       end
 
@@ -119,17 +121,7 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        display_value = @filtered[@selected_index]&.[](:label) || @value
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(display_value)) : Colors.dim(display_value)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
+      def final_display = @filtered[@selected_index]&.[](:label) || @value
 
       private
 

data/lib/clack/prompts/autocomplete_multiselect.rb

@@ -7,10 +7,9 @@ module Clack
     # Combines text input filtering with checkbox-style selection.
     # Type to filter, Space to toggle, Enter to confirm.
     #
-    # Shortcuts:
-    # - Space: toggle current option
-    # - 'a': toggle all options
-    # - 'i': invert selection
+    # Unlike {Multiselect}, the 'a' (select all) and 'i' (invert) shortcuts
+    # are not available because those characters are needed for the search field.
+    # Similarly, vim-style j/k navigation is disabled in favor of typing.
     #
     # @example Basic usage
     #   colors = Clack.autocomplete_multiselect(
@@ -37,12 +36,12 @@ module Clack
       # @param max_items [Integer] max visible options (default: 5)
       # @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 initial_values [Array] 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, filter: nil, **opts)
+      def initialize(message:, options:, max_items: 5, placeholder: nil, required: true, initial_values: [], filter: nil, **opts)
         super(message:, **opts)
         @all_options = normalize_options(options)
         @max_items = max_items
@@ -54,7 +53,7 @@ module Clack
         @selected_index = 0
         @scroll_offset = 0
         valid_values = Set.new(@all_options.map { |o| o[:value] })
-        @selected_values = Set.new(initial_values || []) & valid_values
+        @selected = Set.new(initial_values) & valid_values
         update_filtered
       end
 
@@ -63,78 +62,47 @@ module Clack
       def handle_key(key)
         return if terminal_state?
 
+        # Printable characters always feed the search field (except space, which toggles).
+        # This prevents vim aliases (j/k/h/l) from hijacking text input.
+        if Core::Settings.printable?(key) && key != " "
+          handle_text_input(key)
+          return
+        end
+
         action = Core::Settings.action?(key)
 
         case action
-        when :cancel
-          @state = :cancel
-        when :enter
-          submit_selection
-        when :up
-          move_selection(-1)
-        when :down
-          move_selection(1)
-        when :space
-          toggle_current
-        else
-          handle_char(key)
-        end
-      end
-
-      def handle_char(key)
-        # Shortcut keys only work when search field is empty
-        # to avoid interfering with typing filter text
-        if @search_text.empty?
-          case key&.downcase
-          when "a"
-            toggle_all
-            return
-          when "i"
-            invert_selection
-            return
-          end
+        when :cancel then @state = :cancel
+        when :enter then submit
+        when :up then move_selection(-1)
+        when :down then move_selection(1)
+        when :space then toggle_current
+        else handle_text_input(key)
         end
-        handle_text_input(key)
       end
 
       def toggle_current
         return if @filtered.empty?
 
-        current_value = @filtered[@selected_index][:value]
-        if @selected_values.include?(current_value)
-          @selected_values.delete(current_value)
-        else
-          @selected_values.add(current_value)
-        end
-      end
+        opt = @filtered[@selected_index]
+        return if opt[:disabled]
 
-      def toggle_all
-        if @selected_values.size == @all_options.size
-          @selected_values.clear
+        if @selected.include?(opt[:value])
+          @selected.delete(opt[:value])
         else
-          @all_options.each { |opt| @selected_values.add(opt[:value]) }
+          @selected.add(opt[:value])
         end
       end
 
-      def invert_selection
-        @all_options.each do |opt|
-          if @selected_values.include?(opt[:value])
-            @selected_values.delete(opt[:value])
-          else
-            @selected_values.add(opt[:value])
-          end
-        end
-      end
-
-      def submit_selection
-        if @required && @selected_values.empty?
+      def submit
+        if @required && @selected.empty?
           @error_message = "Please select at least one option. Press #{Colors.cyan("space")} to select, #{Colors.cyan("enter")} to submit"
           @state = :error
           return
         end
 
-        @value = @selected_values.to_a
-        submit
+        @value = @selected.to_a
+        super
       end
 
       def build_frame
@@ -151,29 +119,19 @@ module Clack
 
         lines << "#{active_bar}  #{Colors.yellow("No matches found")}\n" if @filtered.empty? && !@search_text.empty?
 
-        lines << "#{active_bar}  #{instructions}\n"
-        lines << "#{bar_end}\n"
+        lines << "#{active_bar}  #{keyboard_hints}\n"
 
-        validation_lines = validation_message_lines
-        if validation_lines.any?
-          lines[-1] = validation_lines.first
-          lines.concat(validation_lines[1..])
+        if @state in :error | :warning
+          lines.concat(validation_message_lines)
+        else
+          lines << "#{bar_end}\n"
         end
 
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        labels = @all_options.select { |o| @selected_values.include?(o[:value]) }.map { |o| o[:label] }
-        display_text = labels.join(", ")
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(display_text)) : Colors.dim(display_text)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
+      def final_display
+        @all_options.select { |o| @selected.include?(o[:value]) }.map { |o| o[:label] }.join(", ")
       end
 
       private
@@ -199,12 +157,10 @@ module Clack
         Colors.dim(" (#{@filtered.size} match#{"es" unless @filtered.size == 1})")
       end
 
-      def instructions
+      def keyboard_hints
         Colors.dim([
           "up/down: navigate",
           "space: select",
-          "a: all",
-          "i: invert",
           "enter: confirm"
         ].join(" | "))
       end
@@ -220,8 +176,8 @@ module Clack
       def scroll_items = @filtered
 
       def option_display(opt, active)
-        is_selected = @selected_values.include?(opt[:value])
-        checkbox = if is_selected
+        selected = @selected.include?(opt[:value])
+        checkbox = if selected
           Colors.green(Symbols::S_CHECKBOX_SELECTED)
         else
           Colors.dim(Symbols::S_CHECKBOX_INACTIVE)

data/lib/clack/prompts/confirm.rb

@@ -71,17 +71,7 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        selected = @value ? @active_label : @inactive_label
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(selected)) : Colors.dim(selected)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
+      def final_display = @value ? @active_label : @inactive_label
 
       private
 

data/lib/clack/prompts/date.rb

@@ -99,17 +99,7 @@ module Clack
         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
+      def final_display = formatted_date
 
       private
 
@@ -164,28 +154,7 @@ module Clack
       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
+        update_segment(segment_value + delta, wrap: true)
       end
 
       def handle_digit(digit)
@@ -201,23 +170,38 @@ module Clack
       def commit_input_buffer
         return if @input_buffer.empty?
 
-        value = @input_buffer.to_i
+        update_segment(@input_buffer.to_i)
         @input_buffer = ""
+      end
 
+      def segment_value
         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))
+        when :year then @year
+        when :month then @month
+        when :day then @day
         end
+      end
+
+      def update_segment(value, wrap: false)
+        constrain = wrap ? method(:wrap_value) : :clamp.to_proc
 
+        case current_segment_type
+        when :year then @year = value.clamp(1, 9999)
+        when :month then @month = constrain.call(value, 1, 12)
+        when :day then @day = constrain.call(value, 1, days_in_month(@year, @month))
+        end
+
+        clamp_day_to_month
         enforce_bounds
       end
 
+      def wrap_value(val, min, max)
+        return min if val > max
+        return max if val < min
+
+        val
+      end
+
       def current_segment_type = FORMATS[@format][:order][@segment]
 
       def days_in_month(year, month)

data/lib/clack/prompts/group_multiselect.rb

@@ -126,18 +126,7 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        labels = selected_options.map { |o| o[:label] }
-        display_text = labels.join(", ")
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(display_text)) : Colors.dim(display_text)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
+      def final_display = selected_options.map { |o| o[:label] }.join(", ")
 
       private
 

data/lib/clack/prompts/multiselect.rb

@@ -103,17 +103,8 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        labels = @options.select { |o| @selected.include?(o[:value]) }.map { |o| o[:label] }
-        display_text = labels.join(", ")
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(display_text)) : Colors.dim(display_text)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
+      def final_display
+        @options.select { |o| @selected.include?(o[:value]) }.map { |o| o[:label] }.join(", ")
       end
 
       private

data/lib/clack/prompts/password.rb

@@ -51,17 +51,7 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        masked = @mask * @value.grapheme_clusters.length
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(masked)) : Colors.dim(masked)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
+      def final_display = @mask * @value.grapheme_clusters.length
 
       private
 

data/lib/clack/prompts/path.rb

@@ -124,17 +124,6 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(@value)) : Colors.dim(@value)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
-
       private
 
       def update_suggestions

data/lib/clack/prompts/range.rb

@@ -67,17 +67,7 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        display = format_value(@value)
-        styled = (@state == :cancel) ? Colors.strikethrough(Colors.dim(display)) : Colors.dim(display)
-        lines << "#{bar}  #{styled}\n"
-
-        lines.join
-      end
+      def final_display = format_value(@value)
 
       private
 

data/lib/clack/prompts/select.rb

@@ -80,17 +80,7 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        label = current_option[:label]
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(label)) : Colors.dim(label)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
+      def final_display = current_option[:label]
 
       private
 

data/lib/clack/prompts/select_key.rb

@@ -63,17 +63,7 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        label = @options.find { |o| o[:value] == @value }&.dig(:label).to_s
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(label)) : Colors.dim(label)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
+      def final_display = @options.find { |o| o[:value] == @value }&.dig(:label).to_s
 
       private
 

data/lib/clack/prompts/text.rb

@@ -104,17 +104,6 @@ module Clack
         lines.join
       end
 
-      def build_final_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-
-        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(@value)) : Colors.dim(@value)
-        lines << "#{bar}  #{display}\n"
-
-        lines.join
-      end
-
       private
 
       # Complete the current input using the longest common prefix of matching candidates.

data/lib/clack/symbols.rb

@@ -26,8 +26,7 @@ module Clack
         # Explicit override
         return ENV["CLACK_UNICODE"] == "1" if ENV["CLACK_UNICODE"]
 
-        # Default: TTY and not dumb terminal
-        $stdout.tty? && ENV["TERM"] != "dumb" && !ENV["NO_COLOR"]
+        Environment.colors_supported?
       end
     end
 
@@ -36,7 +35,7 @@ module Clack
     # Unicode cancel step indicator, or ASCII fallback.
     S_STEP_CANCEL = unicode? ? "■" : "x"
     # Unicode error step indicator, or ASCII fallback.
-    S_STEP_ERROR = unicode? ? "▲" : "x"
+    S_STEP_ERROR = unicode? ? "▲" : "!"
     # Unicode submit step indicator, or ASCII fallback.
     S_STEP_SUBMIT = unicode? ? "◇" : "o"
 

data/lib/clack/version.rb

@@ -2,5 +2,5 @@
 
 module Clack
   # Current gem version.
-  VERSION = "0.4.4"
+  VERSION = "0.4.6"
 end

data/lib/clack.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "clack/version"
+require_relative "clack/environment"
 require_relative "clack/symbols"
 require_relative "clack/colors"
-require_relative "clack/environment"
 require_relative "clack/utils"
 require_relative "clack/core/cursor"
 require_relative "clack/core/settings"
@@ -508,15 +508,20 @@ module Clack
   end
 end
 
-# Terminal cleanup on exit - show cursor if it was hidden
+# Terminal cleanup on exit — show cursor if it was hidden.
+# Uses raw write(2) for async-signal safety in trap handlers.
+CURSOR_SHOW = "\e[?25h"
+
 at_exit do
-  print "\e[?25h"
+  $stdout.print Clack::Core::Cursor.show
+rescue IOError, SystemCallError
+  # Output unavailable
 end
 
-# Chain INT handler to restore cursor before passing to previous handler
+# Chain INT handler to restore cursor before passing to previous handler.
 previous_int_handler = trap("INT") do
   begin
-    print "\e[?25h"
+    $stdout.write_nonblock(CURSOR_SHOW)
   rescue IOError, SystemCallError
     # Output unavailable — nothing we can do
   end
@@ -532,10 +537,10 @@ previous_int_handler = trap("INT") do
   end
 end
 
-# Handle SIGTERM similarly to INT — restore cursor on graceful kill
+# Handle SIGTERM similarly to INT — restore cursor on graceful kill.
 trap("TERM") do
   begin
-    print "\e[?25h"
+    $stdout.write_nonblock(CURSOR_SHOW)
   rescue IOError, SystemCallError
     # Output unavailable
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clack
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.6
 platform: ruby
 authors:
 - Steve Whittaker
@@ -34,6 +34,8 @@ files:
 - examples/images/select_example.rb
 - examples/images/spinner_example.rb
 - examples/images/text_example.rb
+- examples/migration_from_tty_prompt.rb
+- examples/showcase.rb
 - examples/spinner_demo.rb
 - examples/tasks_demo.rb
 - examples/validation.rb
@@ -101,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Beautiful, minimal CLI prompts
 test_files: []