clack 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3035b53cb615be8f42827389fc118990457a06e20e9a118c9eb77a97ff5352f8
-  data.tar.gz: 98b12f8e74d475a50987a10c719f231050d83484989acd101c4e03bf11ad4b5e
+  metadata.gz: 150bf149feda282a5c07f5e4db2c307bb770b55492a93550937dd0374da6a6cb
+  data.tar.gz: a7468424209339c0ef1dd608a8c332f722a5293c8a5a01097760514602b2d601
 SHA512:
-  metadata.gz: 770e87fe78a09c35ed8150aaee98dbc75ccadb8d23ba39a2b2ba684e00e5cf50b536e1cc0bce00aee9e9aaf22baa2dad566c75c0f64d7b80d799a70009bd2057
-  data.tar.gz: f77bf005240ce8533d1b1110bcd430409847fa9263682df3b7362c72b599570a77ad9eb2fad31bbc8690599348bdbd026a05733d5dad357aaa9824120382c8f5
+  metadata.gz: 37b1e190c92651377058ee130eef9126ce08da57ed24354f1a517e745585a3ec497f1ddb62799762dfe49333201541aad867d8f14f0b286534ecea7f40f39860
+  data.tar.gz: 0da475188a4c750f5a2d892e47fe5a1eae58f2606032e1820cc4f614cce81e2f518e15a9c822ebd02978d99efca418f4135449dd15019c6c14fa698c95811adb

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-01-23
+
+### Added
+- Warning validation: Validators can return `Clack::Warning.new(message)` for soft failures that allow user confirmation
+- Built-in warning validators: `Validators.file_exists_warning` and `Validators.as_warning(validator)`
+- Test coverage for warning state machine and multiselect keyboard shortcuts
+
+### Changed
+- Simplified Multiselect implementation by using base class warning/error handling (37 lines → 12 lines)
+- Unified validation message rendering across all prompt types
+
 ## [0.1.2]
 
 ### Added

data/README.md

@@ -5,7 +5,7 @@
 A faithful Ruby port of [@clack/prompts](https://github.com/bombshell-dev/clack).
 
 <p align="center">
-  <img src="examples/demo.gif" width="640" alt="Clack demo">
+  <img src="examples/demo.gif?v=2" width="640" alt="Clack demo">
 </p>
 
 ## Why Clack?
@@ -76,10 +76,17 @@ ruby examples/full_demo.rb
 <details>
 <summary>Recording the demo GIF</summary>
 
-Install [VHS](https://github.com/charmbracelet/vhs) and run:
+Requires [asciinema](https://asciinema.org/), [agg](https://github.com/asciinema/agg), and [expect](https://core.tcl-lang.org/expect/index):
 
 ```bash
-vhs examples/demo.tape
+# Record the demo (automated via expect script)
+asciinema rec examples/demo.cast --command "expect examples/demo.exp" --overwrite -q
+
+# Split batched frames to show typing (Ruby buffers terminal output)
+ruby examples/split_cast.rb
+
+# Convert to GIF
+agg examples/demo.cast examples/demo.gif --font-size 18 --cols 80 --rows 28 --speed 0.6
 ```
 </details>
 
@@ -93,8 +100,76 @@ result = Clack.text(message: "Name?")
 exit 1 if Clack.cancel?(result)
 ```
 
+### Validation & Transforms
+
+Prompts support `validate:` and `transform:` options.
+
+```
+User Input → Validation (raw) → Transform (if valid) → Final Value
+```
+
+Validation returns an error message, a `Clack::Warning`, or `nil` to pass. Transforms normalize the value after validation passes.
+
+**Validation results:**
+- `nil` or `false` - passes validation
+- String - shows error (red), user must fix input
+- `Clack::Warning.new(message)` - shows warning (yellow), user can confirm with Enter or edit
+
+```ruby
+# Use symbol shortcuts (preferred)
+name = Clack.text(message: "Name?", transform: :strip)
+code = Clack.text(message: "Code?", transform: :upcase)
+
+# Chain multiple transforms
+username = Clack.text(
+  message: "Username?",
+  transform: Clack::Transformers.chain(:strip, :downcase)
+)
+
+# Combine validation and transform
+amount = Clack.text(
+  message: "Amount?",
+  validate: ->(v) { "Must be a number" unless v.match?(/\A\d+\z/) },
+  transform: :to_integer
+)
+
+# Warning validation (soft failure, user can confirm or edit)
+file = Clack.text(
+  message: "Output file?",
+  validate: ->(v) { Clack::Warning.new("File exists. Overwrite?") if File.exist?(v) }
+)
+```
+
+Built-in validators and transformers:
+
+```ruby
+# Validators - return error message, Warning, or nil
+Clack::Validators.required
+Clack::Validators.min_length(8)
+Clack::Validators.format(/\A[a-z]+\z/, "Only lowercase")
+Clack::Validators.email
+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
+
+# Transformers - normalize the value (use :symbol or Clack::Transformers.name)
+:strip / :trim      # Remove leading/trailing whitespace
+:downcase / :upcase # Change case
+:capitalize         # "hello world" -> "Hello world"
+:titlecase          # "hello world" -> "Hello World"
+:squish             # Collapse whitespace to single spaces
+:compact            # Remove all whitespace
+:to_integer         # Parse as integer
+:to_float           # Parse as float
+:digits_only        # Extract only digits
+```
+
 ### Text
 
+<img src="examples/images/text.svg" alt="Text prompt">
+
 ```ruby
 name = Clack.text(
   message: "What is your project named?",
@@ -107,6 +182,8 @@ name = Clack.text(
 
 ### Password
 
+<img src="examples/images/password.svg" alt="Password prompt">
+
 ```ruby
 secret = Clack.password(
   message: "Enter your API key",
@@ -116,6 +193,8 @@ secret = Clack.password(
 
 ### Confirm
 
+<img src="examples/images/confirm.svg" alt="Confirm prompt">
+
 ```ruby
 proceed = Clack.confirm(
   message: "Deploy to production?",
@@ -129,6 +208,8 @@ proceed = Clack.confirm(
 
 Single selection with keyboard navigation.
 
+<img src="examples/images/select.svg" alt="Select prompt">
+
 ```ruby
 db = Clack.select(
   message: "Choose a database",
@@ -146,6 +227,8 @@ db = Clack.select(
 
 Multiple selections with toggle controls.
 
+<img src="examples/images/multiselect.svg" alt="Multiselect prompt">
+
 ```ruby
 features = Clack.multiselect(
   message: "Select features to install",
@@ -223,6 +306,8 @@ action = Clack.select_key(
 
 Non-blocking animated indicator for async work.
 
+<img src="examples/images/spinner.svg" alt="Spinner">
+
 ```ruby
 spinner = Clack.spinner
 spinner.start("Installing dependencies...")

data/lib/clack/core/prompt.rb

@@ -6,7 +6,7 @@ module Clack
   module Core
     # Base class for all interactive prompts.
     #
-    # Implements a state machine with states: :initial, :active, :error, :submit, :cancel.
+    # Implements a state machine with states: :initial, :active, :error, :warning, :submit, :cancel.
     # Subclasses override {#handle_input}, {#build_frame}, and {#build_final_frame}
     # to customize behavior and rendering.
     #
@@ -57,27 +57,33 @@ module Clack
         end
       end
 
-      # @return [Symbol] current state (:initial, :active, :error, :submit, :cancel)
+      # @return [Symbol] current state (:initial, :active, :error, :warning, :submit, :cancel)
       attr_reader :state
       # @return [Object] the current/final value
       attr_reader :value
       # @return [String, nil] validation error message, if any
       attr_reader :error_message
+      # @return [String, nil] validation warning message, if any
+      attr_reader :warning_message
 
       # @param message [String] the prompt message to display
       # @param help [String, nil] optional help text shown below the message
-      # @param validate [Proc, nil] optional validation proc; returns error string or nil
+      # @param validate [Proc, nil] optional validation proc; returns error string, Warning, or nil
+      # @param transform [Symbol, Proc, nil] transformer (symbol shortcut or proc); applied after validation
       # @param input [IO] input stream (default: $stdin)
       # @param output [IO] output stream (default: $stdout)
-      def initialize(message:, help: nil, validate: nil, input: $stdin, output: $stdout)
+      def initialize(message:, help: nil, validate: nil, transform: nil, input: $stdin, output: $stdout)
         @message = message
         @help = help
         @validate = validate
+        @transform = Transformers.resolve(transform)
         @input = input
         @output = output
         @state = :initial
         @value = nil
         @error_message = nil
+        @warning_message = nil
+        @warning_confirmed = false
         @prev_frame = nil
         @cursor = 0
         @needs_redraw = false
@@ -125,10 +131,25 @@ module Clack
       def handle_key(key)
         return if terminal_state?
 
-        @state = :active if @state == :error
-
         action = Settings.action?(key)
 
+        # Handle warning state: Enter confirms, Cancel aborts, other input clears warning
+        if @state == :warning
+          case action
+          when :enter
+            confirm_warning
+            submit
+          when :cancel
+            @state = :cancel
+          else
+            clear_warning
+            handle_input(key, action)
+          end
+          return
+        end
+
+        @state = :active if @state == :error
+
         case action
         when :cancel
           @state = :cancel
@@ -148,17 +169,57 @@ module Clack
       end
 
       # Validate and submit the current value.
-      # Sets state to :error if validation fails, :submit otherwise.
+      # Sets state to :error if validation fails, :warning if warning returned,
+      # or :submit otherwise. Applies transform after successful validation.
       def submit
-        if @validate
-          result = @validate.call(@value)
-          if result
-            @error_message = result.is_a?(Exception) ? result.message : result.to_s
+        @state = validate_value(@value)
+        return unless @state == :submit
+
+        if @transform
+          begin
+            @value = @transform.call(@value)
+          rescue => error
+            @error_message = "Transform failed: #{error.message}"
             @state = :error
-            return
           end
         end
-        @state = :submit
+      end
+
+      # Validate a value and return the resulting state.
+      # Handles errors, warnings, and the warning confirmation flow.
+      #
+      # @param value [Object] the value to validate
+      # @return [Symbol] :submit, :warning, or :error
+      def validate_value(value)
+        return :submit unless @validate
+
+        result = @validate.call(value)
+        return :submit unless result
+
+        if result.is_a?(Warning)
+          return :submit if @warning_confirmed
+
+          @warning_message = result.message
+          :warning
+        else
+          @error_message = result.is_a?(Exception) ? result.message : result.to_s
+          :error
+        end
+      end
+
+      # Clear warning state and return to active.
+      # Call this when user edits input during warning state.
+      def clear_warning
+        @warning_confirmed = false
+        @warning_message = nil
+        @state = :active
+      end
+
+      # Confirm warning and prepare for resubmission.
+      # Call this when user confirms a warning.
+      def confirm_warning
+        @warning_confirmed = true
+        @warning_message = nil
       end
 
       # Render the current frame using differential rendering.
@@ -241,11 +302,11 @@ module Clack
       end
 
       def active_bar
-        (@state == :error) ? Colors.yellow(Symbols::S_BAR) : bar
+        %i[error warning].include?(@state) ? Colors.yellow(Symbols::S_BAR) : bar
       end
 
       def bar_end
-        (@state == :error) ? Colors.yellow(Symbols::S_BAR_END) : Colors.gray(Symbols::S_BAR_END)
+        %i[error warning].include?(@state) ? Colors.yellow(Symbols::S_BAR_END) : Colors.gray(Symbols::S_BAR_END)
       end
 
       def help_line
@@ -263,7 +324,23 @@ module Clack
         when :initial, :active then Colors.cyan(Symbols::S_STEP_ACTIVE)
         when :submit then Colors.green(Symbols::S_STEP_SUBMIT)
         when :cancel then Colors.red(Symbols::S_STEP_CANCEL)
-        when :error then Colors.yellow(Symbols::S_STEP_ERROR)
+        when :error, :warning then Colors.yellow(Symbols::S_STEP_ERROR)
+        end
+      end
+
+      # Build validation message lines for error or warning states.
+      # Returns array of lines to append, or empty array if no validation message.
+      def validation_message_lines
+        case @state
+        when :error
+          ["#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n"]
+        when :warning
+          [
+            "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@warning_message)}\n",
+            "#{bar}  #{Colors.dim("Press Enter to confirm, or edit your input")}\n"
+          ]
+        else
+          []
         end
       end
     end

data/lib/clack/prompts/multiselect.rb

@@ -50,17 +50,8 @@ module Clack
 
       protected
 
-      def handle_key(key)
-        return if terminal_state?
-
-        @state = :active if @state == :error
-        action = Core::Settings.action?(key)
-
+      def handle_input(key, action)
         case action
-        when :cancel
-          @state = :cancel
-        when :enter
-          submit
         when :up
           move_cursor(-1)
         when :down
@@ -101,9 +92,12 @@ module Clack
           lines << "#{active_bar}  #{option_display(opt, actual_idx)}\n"
         end
 
-        lines << "#{bar_end}\n"
-
-        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
+        if @state == :error || @state == :warning
+          lines.concat(validation_message_lines)
+        else
+          lines << "#{bar}  #{keyboard_hints}\n"
+          lines << "#{bar_end}\n"
+        end
 
         lines.join
       end
@@ -162,6 +156,15 @@ module Clack
         @value = @selected.to_a
       end
 
+      def keyboard_hints
+        hints = [
+          "#{Colors.dim("space")} select",
+          "#{Colors.dim("a")} all",
+          "#{Colors.dim("i")} invert"
+        ]
+        Colors.dim(hints.join(Colors.dim(" / ")))
+      end
+
       def option_display(opt, idx)
         active = idx == @cursor
         selected = @selected.include?(opt[:value])

data/lib/clack/prompts/password.rb

@@ -45,7 +45,11 @@ module Clack
         lines << "#{active_bar}  #{masked_display}\n"
         lines << "#{bar_end}\n"
 
-        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
+        validation_lines = validation_message_lines
+        if validation_lines.any?
+          lines[-1] = validation_lines.first
+          lines.concat(validation_lines[1..])
+        end
 
         lines.join
       end

data/lib/clack/prompts/path.rb

@@ -48,17 +48,8 @@ module Clack
 
       protected
 
-      def handle_key(key)
-        return if terminal_state?
-
-        @state = :active if @state == :error
-        action = Core::Settings.action?(key)
-
+      def handle_input(key, action)
         case action
-        when :cancel
-          @state = :cancel
-        when :enter
-          submit_selection
         when :up
           move_selection(-1)
         when :down
@@ -89,7 +80,7 @@ module Clack
         update_suggestions
       end
 
-      def submit_selection
+      def submit
         path = @value.empty? ? @root : resolve_path(@value)
 
         unless path_within_root?(path)
@@ -98,17 +89,14 @@ module Clack
           return
         end
 
-        if @validate
-          result = @validate.call(path)
-          if result
-            @error_message = result.is_a?(Exception) ? result.message : result.to_s
-            @state = :error
-            return
-          end
-        end
-
+        # Temporarily set value to resolved path for validation
+        original_value = @value
         @value = path
-        @state = :submit
+
+        super
+
+        # Restore input buffer if validation or transform failed (but not for warnings)
+        @value = original_value if @state == :error || @state == :warning
       end
 
       def build_frame
@@ -125,7 +113,11 @@ module Clack
 
         lines << "#{bar_end}\n"
 
-        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
+        validation_lines = validation_message_lines
+        if validation_lines.any?
+          lines[-1] = validation_lines.first
+          lines.concat(validation_lines[1..])
+        end
 
         lines.join
       end

data/lib/clack/prompts/text.rb

@@ -74,7 +74,11 @@ module Clack
         lines << "#{active_bar}  #{input_display}\n"
         lines << "#{bar_end}\n" if @state == :active || @state == :initial
 
-        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
+        validation_lines = validation_message_lines
+        if validation_lines.any?
+          lines[-1] = validation_lines.first
+          lines.concat(validation_lines[1..])
+        end
 
         lines.join
       end

data/lib/clack/transformers.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Clack
+  # Built-in transformers for normalizing user input.
+  # Use these with the `transform:` option on prompts.
+  #
+  # Transforms are applied after validation passes, so you can validate
+  # the raw input and transform it into a normalized form.
+  #
+  # @example Using symbol shortcuts (preferred)
+  #   Clack.text(message: "Name?", transform: :strip)
+  #   Clack.text(message: "Code?", transform: :upcase)
+  #
+  # @example Using module methods
+  #   Clack.text(message: "Name?", transform: Clack::Transformers.strip)
+  #
+  # @example Custom transformer
+  #   Clack.text(
+  #     message: "Amount?",
+  #     transform: ->(v) { v.to_f.round(2) }
+  #   )
+  #
+  # @example Chaining multiple transforms
+  #   Clack.text(
+  #     message: "Username?",
+  #     transform: Clack::Transformers.chain(:strip, :downcase)
+  #   )
+  #
+  module Transformers
+    # Lookup table for symbol shortcuts
+    REGISTRY = {}
+
+    class << self
+      # Resolve a transformer from a symbol, proc, or return as-is.
+      # @param transformer [Symbol, Proc, nil] the transformer to resolve
+      # @return [Proc, nil] the resolved transformer proc
+      def resolve(transformer)
+        case transformer
+        when Symbol
+          REGISTRY[transformer] || raise(ArgumentError, "Unknown transformer: #{transformer}")
+        when Proc
+          transformer
+        when nil
+          nil
+        else
+          raise ArgumentError, "Transform must be a Symbol or Proc, got #{transformer.class}"
+        end
+      end
+
+      # Strip leading/trailing whitespace.
+      # @return [Proc] Transformer proc
+      def strip
+        REGISTRY[:strip]
+      end
+
+      # Alias for strip (for JS developers).
+      # @return [Proc] Transformer proc
+      def trim
+        REGISTRY[:trim]
+      end
+
+      # Convert to lowercase.
+      # @return [Proc] Transformer proc
+      def downcase
+        REGISTRY[:downcase]
+      end
+
+      # Convert to uppercase.
+      # @return [Proc] Transformer proc
+      def upcase
+        REGISTRY[:upcase]
+      end
+
+      # Capitalize first letter, lowercase rest.
+      # @return [Proc] Transformer proc
+      def capitalize
+        REGISTRY[:capitalize]
+      end
+
+      # Capitalize first letter of each word.
+      # @return [Proc] Transformer proc
+      def titlecase
+        REGISTRY[:titlecase]
+      end
+
+      # Strip and collapse whitespace to single spaces.
+      # @return [Proc] Transformer proc
+      def squish
+        REGISTRY[:squish]
+      end
+
+      # Remove all whitespace.
+      # @return [Proc] Transformer proc
+      def compact
+        REGISTRY[:compact]
+      end
+
+      # Parse as integer.
+      # @return [Proc] Transformer proc
+      def to_integer
+        REGISTRY[:to_integer]
+      end
+
+      # Parse as float.
+      # @return [Proc] Transformer proc
+      def to_float
+        REGISTRY[:to_float]
+      end
+
+      # Extract only digits.
+      # @return [Proc] Transformer proc
+      def digits_only
+        REGISTRY[:digits_only]
+      end
+
+      # Combine multiple transformers, applied in order.
+      # Accepts symbols or procs.
+      #
+      # @param transformers [Array<Symbol, Proc>] Transformers to combine
+      # @return [Proc] Combined transformer proc
+      #
+      # @example
+      #   Clack::Transformers.chain(:strip, :downcase)
+      #   Clack::Transformers.chain(:strip, ->(v) { v.reverse })
+      def chain(*transformers)
+        resolved = transformers.map { |xform| resolve(xform) }
+        ->(value) { resolved.reduce(value) { |val, xform| xform.call(val) } }
+      end
+    end
+
+    # Register built-in transformers
+    REGISTRY[:strip] = ->(value) { value.to_s.strip }
+    REGISTRY[:trim] = REGISTRY[:strip]
+    REGISTRY[:downcase] = ->(value) { value.to_s.downcase }
+    REGISTRY[:upcase] = ->(value) { value.to_s.upcase }
+    REGISTRY[:capitalize] = ->(value) { value.to_s.capitalize }
+    REGISTRY[:titlecase] = ->(value) { value.to_s.split.map(&:capitalize).join(" ") }
+    REGISTRY[:squish] = ->(value) { value.to_s.strip.gsub(/\s+/, " ") }
+    REGISTRY[:compact] = ->(value) { value.to_s.gsub(/\s+/, "") }
+    REGISTRY[:to_integer] = ->(value) { value.to_s.to_i }
+    REGISTRY[:to_float] = ->(value) { value.to_s.to_f }
+    REGISTRY[:digits_only] = ->(value) { value.to_s.gsub(/\D/, "") }
+  end
+end

data/lib/clack/validators.rb

@@ -142,6 +142,38 @@ module Clack
         ->(value) { message unless File.directory?(value.to_s) }
       end
 
+      # Warning if file exists. Allows user to confirm overwrite.
+      #
+      # @param message [String] Warning message
+      # @return [Proc] Validator proc returning Warning
+      #
+      # @example
+      #   Clack.text(message: "Output file?", validate: Clack::Validators.file_exists_warning)
+      def file_exists_warning(message = "File already exists. Overwrite?")
+        ->(value) { Clack::Warning.new(message) if File.exist?(value.to_s) }
+      end
+
+      # Convert any validator to return a warning instead of an error.
+      # Warnings allow the user to proceed with confirmation.
+      #
+      # @param validator [Proc] Original validator
+      # @return [Proc] Validator that returns Warning instead of String
+      #
+      # @example
+      #   # Make max_length a warning instead of error
+      #   Clack.text(
+      #     message: "Bio?",
+      #     validate: Clack::Validators.as_warning(
+      #       Clack::Validators.max_length(100, "Bio is quite long")
+      #     )
+      #   )
+      def as_warning(validator)
+        lambda do |value|
+          result = validator.call(value)
+          Clack::Warning.new(result) if result
+        end
+      end
+
       private
 
       def first_failing_validation(validators, value)

data/lib/clack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clack
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/clack.rb

@@ -32,6 +32,7 @@ require_relative "clack/group"
 require_relative "clack/stream"
 require_relative "clack/task_log"
 require_relative "clack/validators"
+require_relative "clack/transformers"
 
 # Clack - Beautiful CLI prompts for Ruby
 #
@@ -55,7 +56,28 @@ module Clack
   # Sentinel value returned when user cancels a prompt (Escape or Ctrl+C)
   CANCEL = Object.new.tap { |o| o.define_singleton_method(:inspect) { "Clack::CANCEL" } }.freeze
 
+  # Warning result from validation - allows user to proceed with confirmation.
+  # Validators can return a Warning to show a yellow message that doesn't block
+  # submission if the user confirms by pressing Enter again.
+  #
+  # @example Validator returning a warning
+  #   validate: ->(v) { Clack::Warning.new("File exists, overwrite?") if File.exist?(v) }
+  Warning = Data.define(:message) do
+    def to_s = message
+  end
+
   class << self
+    # Create a validation warning that allows the user to proceed with confirmation.
+    #
+    # @param message [String] the warning message
+    # @return [Warning] a warning object
+    #
+    # @example
+    #   validate: ->(v) { Clack.warning("Unusual value") if v.length > 100 }
+    def warning(message)
+      Warning.new(message)
+    end
+
     # Check if a prompt result was cancelled by the user.
     #
     # @param value [Object] the result from a prompt
@@ -123,7 +145,9 @@ module Clack
     # @param placeholder [String, nil] dim text shown when input is empty
     # @param default_value [String, nil] value used if submitted empty
     # @param initial_value [String, nil] pre-filled editable text
-    # @param validate [Proc, nil] validation function returning error message or nil
+    # @param validate [Proc, nil] validation function returning error string, Warning, or nil
+    # @param transform [Symbol, Proc, nil] transform function to normalize the value
+    # @param help [String, nil] help text shown below the message
     # @return [String, CANCEL] user input or CANCEL if cancelled
     def text(message:, **opts)
       Prompts::Text.new(message:, **opts).run
@@ -136,7 +160,8 @@ module Clack
     #
     # @param message [String] the prompt message
     # @param initial_value [String, nil] pre-filled editable text (can contain newlines)
-    # @param validate [Proc, nil] validation function returning error message or nil
+    # @param validate [Proc, nil] validation function returning error string, Warning, or nil
+    # @param help [String, nil] help text shown below the message
     # @return [String, CANCEL] user input (lines joined with \n) or CANCEL if cancelled
     def multiline_text(message:, **opts)
       Prompts::MultilineText.new(message:, **opts).run
@@ -146,7 +171,8 @@ module Clack
     #
     # @param message [String] the prompt message
     # @param mask [String] character to display for each input character (default: ▪)
-    # @param validate [Proc, nil] validation function
+    # @param validate [Proc, nil] validation function returning error string, Warning, or nil
+    # @param help [String, nil] help text shown below the message
     # @return [String, CANCEL] password or CANCEL if cancelled
     def password(message:, **opts)
       Prompts::Password.new(message:, **opts).run

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clack
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Steve Whittaker
@@ -52,6 +52,7 @@ files:
 - lib/clack/stream.rb
 - lib/clack/symbols.rb
 - lib/clack/task_log.rb
+- lib/clack/transformers.rb
 - lib/clack/utils.rb
 - lib/clack/validators.rb
 - lib/clack/version.rb