clack 0.1.4 → 0.2.0

data/examples/group_demo.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demonstrates Clack.group and group_multiselect
+# Run with: ruby examples/group_demo.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "group-demo"
+
+# Prompt group with on_cancel handler
+result = Clack.group(
+  on_cancel: ->(partial) {
+    Clack.cancel "Cancelled (collected: #{partial.keys.select { |k| partial[k] != :cancelled }.join(", ")})"
+    exit 0
+  }
+) do |g|
+  g.prompt(:name) { Clack.text(message: "Project name:", placeholder: "my-project") }
+
+  g.prompt(:visibility) do |results|
+    Clack.select(
+      message: "Visibility for #{results[:name]}?",
+      options: [
+        {value: "public", label: "Public", hint: "visible to everyone"},
+        {value: "private", label: "Private", hint: "invite only"}
+      ]
+    )
+  end
+
+  g.prompt(:confirm) do |results|
+    Clack.confirm(message: "Create #{results[:visibility]} project '#{results[:name]}'?")
+  end
+end
+
+unless result[:confirm]
+  Clack.outro "Project creation skipped."
+  exit 0
+end
+
+Clack.log.success "Project: #{result[:name]} (#{result[:visibility]})"
+
+# Group multiselect with selectable group headers and spacing
+stack = Clack.group_multiselect(
+  message: "Select stack components:",
+  selectable_groups: true,
+  group_spacing: 1,
+  required: true,
+  options: [
+    {
+      label: "Frontend",
+      options: [
+        {value: "react", label: "React"},
+        {value: "tailwind", label: "Tailwind CSS"},
+        {value: "typescript", label: "TypeScript"}
+      ]
+    },
+    {
+      label: "Backend",
+      options: [
+        {value: "rails", label: "Ruby on Rails"},
+        {value: "sidekiq", label: "Sidekiq"},
+        {value: "graphql", label: "GraphQL"}
+      ]
+    },
+    {
+      label: "Infrastructure",
+      options: [
+        {value: "docker", label: "Docker"},
+        {value: "k8s", label: "Kubernetes"},
+        {value: "terraform", label: "Terraform"}
+      ]
+    }
+  ]
+)
+exit 0 if Clack.cancel?(stack)
+
+Clack.log.step "Stack: #{stack.join(", ")}"
+
+Clack.outro "Done!"

data/examples/images/confirm_example.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/images/confirm_example.rb
+
+require_relative "../../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.confirm(
+  message: "Deploy to production?",
+  active: "Yes, ship it!",
+  inactive: "No, abort"
+)

data/examples/images/multiselect_example.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/images/multiselect_example.rb
+
+require_relative "../../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.multiselect(
+  message: "Select features to install",
+  options: [
+    {value: "api", label: "API Mode"},
+    {value: "auth", label: "Authentication"},
+    {value: "jobs", label: "Background Jobs"}
+  ]
+)

data/examples/images/password_example.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/images/password_example.rb
+
+require_relative "../../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.password(
+  message: "Enter your API key"
+)

data/examples/images/select_example.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/images/select_example.rb
+
+require_relative "../../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.select(
+  message: "Choose a database",
+  options: [
+    {value: "pg", label: "PostgreSQL", hint: "recommended"},
+    {value: "mysql", label: "MySQL"},
+    {value: "sqlite", label: "SQLite"}
+  ]
+)

data/examples/images/spinner_example.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/images/spinner_example.rb
+
+require_relative "../../lib/clack" # Or: require "clack" if installed as a gem
+
+spinner = Clack.spinner
+spinner.start("Installing dependencies...")
+sleep 1.5
+spinner.stop("Dependencies installed!")

data/examples/images/text_example.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/images/text_example.rb
+
+require_relative "../../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.text(
+  message: "What is your project named?",
+  placeholder: "my-project"
+)

data/examples/spinner_demo.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/spinner_demo.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "spinner-demo"
+
+# Success state
+s = Clack.spinner
+s.start "Installing dependencies..."
+sleep 2
+s.stop "Dependencies installed!"
+
+# Update message mid-spin
+s = Clack.spinner
+s.start "Building project..."
+sleep 1
+s.message "Compiling assets..."
+sleep 1
+s.message "Optimizing bundles..."
+sleep 1
+s.stop "Build complete!"
+
+# Error state
+s = Clack.spinner
+s.start "Running tests..."
+sleep 1.5
+s.error "Tests failed!"
+
+# Cancel state
+s = Clack.spinner
+s.start "Deploying to production..."
+sleep 1
+s.cancel "Deployment cancelled"
+
+Clack.outro "Demo complete!"

data/examples/tasks_demo.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demonstrates Clack.tasks and Clack.task_log
+# Run with: ruby examples/tasks_demo.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "tasks-demo"
+
+# Sequential tasks with spinner (message callback updates the spinner text)
+Clack.tasks(tasks: [
+  {
+    title: "Checking dependencies",
+    task: -> {
+      sleep 1
+    }
+  },
+  {
+    title: "Installing packages",
+    task: ->(message) {
+      sleep 0.5
+      message.call("Installing packages... (1/3) core")
+      sleep 0.5
+      message.call("Installing packages... (2/3) dev tools")
+      sleep 0.5
+      message.call("Installing packages... (3/3) plugins")
+      sleep 0.5
+    }
+  },
+  {
+    title: "Compiling assets",
+    task: -> {
+      sleep 1.5
+    }
+  }
+])
+
+# Task log with streaming output
+tl = Clack.task_log(title: "Running test suite", limit: 5)
+
+test_files = %w[
+  models/user_test.rb
+  models/post_test.rb
+  controllers/auth_test.rb
+  controllers/api_test.rb
+  helpers/format_test.rb
+  integration/signup_test.rb
+  integration/login_test.rb
+]
+
+test_files.each do |file|
+  tl.message "Running #{file}..."
+  sleep 0.3
+end
+
+tl.success "All #{test_files.length} test files passed!"
+
+Clack.outro "Done!"

data/examples/validation.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: ruby examples/validation.rb
+
+require_relative "../lib/clack" # Or: require "clack" if installed as a gem
+
+Clack.intro "validation-demo"
+
+# Required field
+name = Clack.text(
+  message: "Username (required)",
+  validate: ->(v) { "Username is required" if v.to_s.strip.empty? }
+)
+exit 0 if Clack.cancel?(name)
+
+# Length validation
+password = Clack.password(
+  message: "Password (min 8 chars)",
+  validate: ->(v) { "Password must be at least 8 characters" if v.to_s.length < 8 }
+)
+exit 0 if Clack.cancel?(password)
+
+# Format validation
+email = Clack.text(
+  message: "Email address",
+  validate: lambda { |v|
+    return "Email is required" if v.to_s.strip.empty?
+    return "Invalid email format" unless v.to_s.include?("@")
+
+    nil
+  }
+)
+exit 0 if Clack.cancel?(email)
+
+# Phone number with validation and custom transform
+phone = Clack.text(
+  message: "Phone number",
+  validate: ->(v) { "Enter 10 digits" unless v.gsub(/\D/, "").length == 10 },
+  transform: ->(v) {
+    digits = v.gsub(/\D/, "")
+    "(#{digits[0, 3]}) #{digits[3, 3]}-#{digits[6, 4]}"
+  }
+)
+exit 0 if Clack.cancel?(phone)
+
+# Username with transform (symbol shortcuts + custom)
+handle = Clack.text(
+  message: "Twitter handle",
+  transform: Clack::Transformers.chain(:strip, :downcase, ->(v) { v.delete_prefix("@") })
+)
+exit 0 if Clack.cancel?(handle)
+
+# Multiselect required
+features = Clack.multiselect(
+  message: "Select at least one feature",
+  options: [
+    {value: "a", label: "Feature A"},
+    {value: "b", label: "Feature B"},
+    {value: "c", label: "Feature C"}
+  ],
+  required: true # Built-in validation
+)
+exit 0 if Clack.cancel?(features)
+
+Clack.log.success "All validations passed!"
+Clack.log.info "Username: #{name}"
+Clack.log.info "Email: #{email}"
+Clack.log.info "Phone: #{phone}"
+Clack.log.info "Handle: @#{handle}"
+Clack.log.info "Features: #{features.join(", ")}"
+
+Clack.outro "Done!"

data/lib/clack/colors.rb

@@ -15,34 +15,128 @@ module Clack
         $stdout.tty?
       end
 
-      # Foreground colors (standard)
+      # @!group Foreground Colors (standard)
+
+      # Apply gray foreground color (ANSI 90).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def gray(text) = wrap(text, "90")
+
+      # Apply cyan foreground color (ANSI 36).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def cyan(text) = wrap(text, "36")
+
+      # Apply green foreground color (ANSI 32).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def green(text) = wrap(text, "32")
+
+      # Apply yellow foreground color (ANSI 33).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def yellow(text) = wrap(text, "33")
+
+      # Apply red foreground color (ANSI 31).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def red(text) = wrap(text, "31")
+
+      # Apply blue foreground color (ANSI 34).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def blue(text) = wrap(text, "34")
+
+      # Apply magenta foreground color (ANSI 35).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def magenta(text) = wrap(text, "35")
+
+      # Apply white foreground color (ANSI 37).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def white(text) = wrap(text, "37")
 
-      # Text styles
+      # @!endgroup
+
+      # @!group Text Styles
+
+      # Apply dim/faint style (ANSI 2).
+      # @param text [#to_s] text to style
+      # @return [String] ANSI-wrapped text
       def dim(text) = wrap(text, "2")
+
+      # Apply bold style (ANSI 1).
+      # @param text [#to_s] text to style
+      # @return [String] ANSI-wrapped text
       def bold(text) = wrap(text, "1")
+
+      # Apply italic style (ANSI 3).
+      # @param text [#to_s] text to style
+      # @return [String] ANSI-wrapped text
       def italic(text) = wrap(text, "3")
+
+      # Apply underline style (ANSI 4).
+      # @param text [#to_s] text to style
+      # @return [String] ANSI-wrapped text
       def underline(text) = wrap(text, "4")
+
+      # Apply inverse/reverse video style (ANSI 7).
+      # @param text [#to_s] text to style
+      # @return [String] ANSI-wrapped text
       def inverse(text) = wrap(text, "7")
+
+      # Apply strikethrough style (ANSI 9).
+      # @param text [#to_s] text to style
+      # @return [String] ANSI-wrapped text
       def strikethrough(text) = wrap(text, "9")
+
+      # Apply hidden/invisible style (ANSI 8).
+      # @param text [#to_s] text to style
+      # @return [String] ANSI-wrapped text
       def hidden(text) = wrap(text, "8")
 
-      # Bright/vivid foreground colors (higher contrast)
+      # @!endgroup
+
+      # @!group Bright Foreground Colors (high contrast)
+
+      # Apply bright cyan foreground color (ANSI 96).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def bright_cyan(text) = wrap(text, "96")
+
+      # Apply bright green foreground color (ANSI 92).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def bright_green(text) = wrap(text, "92")
+
+      # Apply bright yellow foreground color (ANSI 93).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def bright_yellow(text) = wrap(text, "93")
+
+      # Apply bright red foreground color (ANSI 91).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def bright_red(text) = wrap(text, "91")
+
+      # Apply bright blue foreground color (ANSI 94).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def bright_blue(text) = wrap(text, "94")
+
+      # Apply bright magenta foreground color (ANSI 95).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def bright_magenta(text) = wrap(text, "95")
+
+      # Apply bright white foreground color (ANSI 97).
+      # @param text [#to_s] text to colorize
+      # @return [String] ANSI-wrapped text
       def bright_white(text) = wrap(text, "97")
 
+      # @!endgroup
+
       private
 
       def wrap(text, code)

data/lib/clack/core/cursor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Clack
+  # Core building blocks for prompt rendering and interaction.
   module Core
     # ANSI escape sequences for cursor control.
     # See: https://en.wikipedia.org/wiki/ANSI_escape_code

data/lib/clack/core/key_reader.rb

@@ -16,6 +16,11 @@ module Clack
       SEQUENCE_TIMEOUT = 0.01
 
       class << self
+        # Read a single keystroke from the terminal in raw mode.
+        # Handles multi-byte escape sequences (arrow keys, etc.).
+        #
+        # @return [String, nil] the key code, or nil on EOF
+        # @raise [IOError] if no console is available
         def read
           console = IO.console
           raise IOError, "No console available (not a TTY?)" unless console

data/lib/clack/core/prompt.rb

@@ -41,6 +41,7 @@ module Clack
           @active_prompts << prompt
         end
 
+        # Unregister a prompt instance from resize notifications.
         def unregister(prompt)
           @active_prompts.delete(prompt)
         end
@@ -109,7 +110,7 @@ module Clack
 
         loop do
           key = KeyReader.read
-          handle_key(key)
+          dispatch_key(key)
           render
 
           break if terminal_state?
@@ -124,17 +125,26 @@ module Clack
 
       protected
 
-      # Process a keypress and update state accordingly.
-      # Delegates to {#handle_input} for prompt-specific behavior.
+      # Dispatch a keypress, handling warning state before delegating to {#handle_key}.
+      #
+      # This method ensures ALL prompts participate in the warning validation flow,
+      # even those that override {#handle_key}. The run loop calls this instead of
+      # handle_key directly.
+      #
+      # Warning state behavior:
+      # - Enter confirms the warning and re-submits
+      # - Cancel (Escape/Ctrl+C) aborts from warning state
+      # - Any other input clears the warning and delegates to handle_key
+      #
+      # Also clears error state on any keypress, so subclasses don't need to
+      # manage error-to-active transitions themselves.
       #
       # @param key [String] the key code from {KeyReader}
-      def handle_key(key)
+      def dispatch_key(key)
         return if terminal_state?
 
-        action = Settings.action?(key)
-
-        # Handle warning state: Enter confirms, Cancel aborts, other input clears warning
         if @state == :warning
+          action = Settings.action?(key)
           case action
           when :enter
             confirm_warning
@@ -143,13 +153,34 @@ module Clack
             @state = :cancel
           else
             clear_warning
-            handle_input(key, action)
+            handle_key(key)
           end
           return
         end
 
         @state = :active if @state == :error
 
+        handle_key(key)
+      end
+
+      # Process a keypress and update state accordingly.
+      # Delegates to {#handle_input} for prompt-specific behavior.
+      #
+      # Override this in subclasses that need custom key dispatch (e.g., Select,
+      # Confirm, Autocomplete). The warning state and error-clearing are handled
+      # by {#dispatch_key} before this method is called, so overrides do not need
+      # to manage those transitions.
+      #
+      # For prompts that only need custom handling of printable/navigation input
+      # (not cancel/enter), override {#handle_input} instead. That is simpler and
+      # preserves the default cancel/enter behavior from this method.
+      #
+      # @param key [String] the key code from {KeyReader}
+      def handle_key(key)
+        return if terminal_state?
+
+        action = Settings.action?(key)
+
         case action
         when :cancel
           @state = :cancel
@@ -162,6 +193,11 @@ module Clack
 
       # Handle prompt-specific input. Override in subclasses.
       #
+      # This is the simplest extension point for prompts that only need to handle
+      # navigation keys and printable input. Cancel and Enter are handled by
+      # {#handle_key}, and warning/error state transitions are handled by
+      # {#dispatch_key}.
+      #
       # @param key [String] the raw key code
       # @param action [Symbol, nil] the mapped action (:up, :down, etc.) or nil
       def handle_input(key, action)
@@ -188,6 +224,14 @@ module Clack
       # Validate a value and return the resulting state.
       # Handles errors, warnings, and the warning confirmation flow.
       #
+      # Validation contract: the validate proc receives the current value and returns:
+      # - nil or false: validation passes, prompt submits
+      # - String: hard error, prompt enters :error state and displays the message
+      # - Exception: hard error, the exception's message is displayed
+      # - Clack::Warning: soft warning, prompt enters :warning state. The user can
+      #   press Enter to confirm and submit, or edit their input to clear the warning.
+      # - Any other truthy value: treated as an error (to_s is called for the message)
+      #
       # @param value [Object] the value to validate
       # @return [Symbol] :submit, :warning, or :error
       def validate_value(value)

data/lib/clack/core/settings.rb

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

data/lib/clack/core/text_input_helper.rb

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