clack 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9749ca99273a0ed19da8274041da1b04f7355f523761169b509e3234737be7b
-  data.tar.gz: 8a097667af010ba054486e6a22407fefdb021752a9ce018ac2a0489f060f4140
+  metadata.gz: 3035b53cb615be8f42827389fc118990457a06e20e9a118c9eb77a97ff5352f8
+  data.tar.gz: 98b12f8e74d475a50987a10c719f231050d83484989acd101c4e03bf11ad4b5e
 SHA512:
-  metadata.gz: 6aa1f190f08a4fc285e682f6838518951ddc25647eaf034e06bdf7d1b1d06b15b0cc7cb2de3bd4c5ead11adcaea00b7cd8e2c6e8d03f28287b084f187766dd28
-  data.tar.gz: f6b11ea693a6ba6440a907c01b25a33ade736d074eaed61095998b873385466ee1c086ad2bb78546287e2e038a56a4cab23f509c678e3c9ecb752bca6c540907
+  metadata.gz: 770e87fe78a09c35ed8150aaee98dbc75ccadb8d23ba39a2b2ba684e00e5cf50b536e1cc0bce00aee9e9aaf22baa2dad566c75c0f64d7b80d799a70009bd2057
+  data.tar.gz: f77bf005240ce8533d1b1110bcd430409847fa9263682df3b7362c72b599570a77ad9eb2fad31bbc8690599348bdbd026a05733d5dad357aaa9824120382c8f5

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.1.2]
+
+### Added
+- `multiline_text` prompt for multi-line input (Ctrl+D to submit)
+- `help:` option on all prompts for contextual help text
+- Documentation for blocking validation (database/API calls work out of the box)
+
 ## [0.1.1]
 
 ### Fixed

data/lib/clack/core/prompt.rb

@@ -65,11 +65,13 @@ module Clack
       attr_reader :error_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 input [IO] input stream (default: $stdin)
       # @param output [IO] output stream (default: $stdout)
-      def initialize(message:, validate: nil, input: $stdin, output: $stdout)
+      def initialize(message:, help: nil, validate: nil, input: $stdin, output: $stdout)
         @message = message
+        @help = help
         @validate = validate
         @input = input
         @output = output
@@ -246,6 +248,12 @@ module Clack
         (@state == :error) ? Colors.yellow(Symbols::S_BAR_END) : Colors.gray(Symbols::S_BAR_END)
       end
 
+      def help_line
+        return "" unless @help
+
+        "#{bar}  #{Colors.dim(@help)}\n"
+      end
+
       def cursor_block
         Colors.inverse(" ")
       end

data/lib/clack/core/settings.rb

@@ -10,6 +10,7 @@ module Clack
       KEY_BACKSPACE = "\b"        # ASCII 8: Backspace
       KEY_DELETE = "\u007F"       # ASCII 127: Delete (often sent by backspace key)
       KEY_CTRL_C = "\u0003"       # ASCII 3: Ctrl+C (interrupt)
+      KEY_CTRL_D = "\u0004"       # ASCII 4: Ctrl+D (EOF, used for multiline submit)
       KEY_ESCAPE = "\e"           # ASCII 27: Escape
       KEY_ENTER = "\r"            # ASCII 13: Carriage return
       KEY_NEWLINE = "\n"          # ASCII 10: Line feed

data/lib/clack/prompts/autocomplete.rb

@@ -89,6 +89,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
 
         visible_options.each_with_index do |opt, idx|

data/lib/clack/prompts/autocomplete_multiselect.rb

@@ -136,6 +136,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{Colors.dim("Search:")} #{search_input_display}#{match_count}\n"
 
         visible_options.each_with_index do |opt, idx|

data/lib/clack/prompts/confirm.rb

@@ -65,6 +65,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{bar}  #{options_display}\n"
         lines << "#{Colors.gray(Symbols::S_BAR_END)}\n"
         lines.join

data/lib/clack/prompts/group_multiselect.rb

@@ -59,6 +59,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         prev_was_group = false
         @flat_items.each_with_index do |item, idx|

data/lib/clack/prompts/multiline_text.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Multi-line text input prompt with line navigation.
+    #
+    # Features:
+    # - Enter inserts newline, Ctrl+D submits
+    # - Arrow key navigation (up/down between lines, left/right within line)
+    # - Backspace merges lines when at line start
+    # - Validation support
+    #
+    # @example Basic usage
+    #   message = Clack.multiline_text(message: "Enter your commit message:")
+    #
+    # @example With initial value and validation
+    #   content = Clack.multiline_text(
+    #     message: "Description:",
+    #     initial_value: "feat: ",
+    #     validate: ->(v) { "Required!" if v.strip.empty? }
+    #   )
+    #
+    class MultilineText < Core::Prompt
+      # @param message [String] the prompt message
+      # @param initial_value [String, nil] pre-filled editable text (can contain newlines)
+      # @param validate [Proc, nil] validation proc returning error string or nil
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, initial_value: nil, **opts)
+        super(message:, **opts)
+        @lines = parse_initial_value(initial_value)
+        @line_index = @lines.length - 1
+        @column = current_line.grapheme_clusters.length
+      end
+
+      protected
+
+      def handle_key(key)
+        return if terminal_state?
+
+        @state = :active if @state == :error
+
+        case key
+        when Core::Settings::KEY_CTRL_D
+          submit
+        when Core::Settings::KEY_ESCAPE, Core::Settings::KEY_CTRL_C
+          @state = :cancel
+        when Core::Settings::KEY_ENTER, Core::Settings::KEY_NEWLINE
+          insert_newline
+        else
+          handle_input(key)
+        end
+      end
+
+      def handle_input(key)
+        case key
+        when "\e[A" then move_up
+        when "\e[B" then move_down
+        when "\e[C" then move_right
+        when "\e[D" then move_left
+        else handle_text_input(key)
+        end
+      end
+
+      def submit
+        @value = @lines.join("\n")
+        super
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message} #{Colors.dim("(Ctrl+D to submit)")}\n"
+        lines << help_line
+
+        @lines.each_with_index do |line, idx|
+          display = (idx == @line_index) ? line_with_cursor(line) : line
+          lines << "#{active_bar}  #{display}\n"
+        end
+
+        lines << "#{bar_end}\n"
+        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
+
+        lines.join
+      end
+
+      def build_final_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+
+        if @state == :cancel
+          @lines.each { |line| lines << "#{bar}  #{Colors.strikethrough(Colors.dim(line))}\n" }
+        else
+          @lines.each { |line| lines << "#{bar}  #{Colors.dim(line)}\n" }
+        end
+
+        lines.join
+      end
+
+      private
+
+      def parse_initial_value(value)
+        return [""] if value.nil? || value.empty?
+
+        value.split("\n", -1) # -1 preserves trailing empty strings
+      end
+
+      def current_line
+        @lines[@line_index] || ""
+      end
+
+      def line_with_cursor(line)
+        chars = line.grapheme_clusters
+        return cursor_block if chars.empty?
+        return "#{line}#{cursor_block}" if @column >= chars.length
+
+        before = chars[0...@column].join
+        current = Colors.inverse(chars[@column])
+        after = chars[(@column + 1)..].join
+        "#{before}#{current}#{after}"
+      end
+
+      def insert_newline
+        chars = current_line.grapheme_clusters
+        before = chars[0...@column].join
+        after = chars[@column..].join
+
+        @lines[@line_index] = before
+        @lines.insert(@line_index + 1, after)
+        @line_index += 1
+        @column = 0
+      end
+
+      def move_up
+        return if @line_index.zero?
+
+        @line_index -= 1
+        clamp_column
+      end
+
+      def move_down
+        return if @line_index >= @lines.length - 1
+
+        @line_index += 1
+        clamp_column
+      end
+
+      def move_left
+        return if @column.zero?
+
+        @column -= 1
+      end
+
+      def move_right
+        max = current_line.grapheme_clusters.length
+        return if @column >= max
+
+        @column += 1
+      end
+
+      def clamp_column
+        max = current_line.grapheme_clusters.length
+        @column = [@column, max].min
+      end
+
+      def handle_text_input(key)
+        return handle_backspace if Core::Settings.backspace?(key)
+        return unless Core::Settings.printable?(key)
+
+        chars = current_line.grapheme_clusters
+        chars.insert(@column, key)
+        @lines[@line_index] = chars.join
+        @column += 1
+      end
+
+      def handle_backspace
+        if @column.zero?
+          return if @line_index.zero?
+
+          merge_line_up
+        else
+          chars = current_line.grapheme_clusters
+          chars.delete_at(@column - 1)
+          @lines[@line_index] = chars.join
+          @column -= 1
+        end
+      end
+
+      def merge_line_up
+        return if @line_index.zero?
+
+        current_content = @lines.delete_at(@line_index)
+        @line_index -= 1
+        prev_length = current_line.grapheme_clusters.length
+        @lines[@line_index] = current_line + current_content
+        @column = prev_length
+      end
+    end
+  end
+end

data/lib/clack/prompts/multiselect.rb

@@ -94,6 +94,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx

data/lib/clack/prompts/password.rb

@@ -41,6 +41,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{masked_display}\n"
         lines << "#{bar_end}\n"
 

data/lib/clack/prompts/path.rb

@@ -115,6 +115,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
 
         visible_suggestions.each_with_index do |path, idx|

data/lib/clack/prompts/select.rb

@@ -69,6 +69,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx

data/lib/clack/prompts/select_key.rb

@@ -55,6 +55,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         @options.each do |opt|
           lines << "#{bar}  #{option_display(opt)}\n"

data/lib/clack/prompts/text.rb

@@ -70,6 +70,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
         lines << "#{bar_end}\n" if @state == :active || @state == :initial
 

data/lib/clack/validators.rb

@@ -4,11 +4,22 @@ module Clack
   # Built-in validators for common validation patterns.
   # Use these with the `validate:` option on prompts.
   #
+  # Validation procs can perform any operation including slow I/O (database
+  # lookups, API calls, etc.) - they simply block until complete.
+  #
   # @example Using built-in validators
   #   Clack.text(message: "Name?", validate: Clack::Validators.required)
   #   Clack.text(message: "Email?", validate: Clack::Validators.format(/@/, "Must be an email"))
   #   Clack.password(message: "Password?", validate: Clack::Validators.min_length(8))
   #
+  # @example Database validation (blocking I/O)
+  #   Clack.text(
+  #     message: "Email?",
+  #     validate: ->(email) {
+  #       "Already taken" if User.exists?(email: email)
+  #     }
+  #   )
+  #
   # @example Combining validators
   #   Clack.text(
   #     message: "Username?",

data/lib/clack/version.rb

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

data/lib/clack.rb

@@ -12,6 +12,7 @@ require_relative "clack/core/prompt"
 require_relative "clack/core/options_helper"
 require_relative "clack/core/text_input_helper"
 require_relative "clack/prompts/text"
+require_relative "clack/prompts/multiline_text"
 require_relative "clack/prompts/password"
 require_relative "clack/prompts/confirm"
 require_relative "clack/prompts/select"
@@ -128,6 +129,19 @@ module Clack
       Prompts::Text.new(message:, **opts).run
     end
 
+    # Prompt for multi-line text input.
+    #
+    # Enter inserts a newline, Ctrl+D submits. Useful for commit messages,
+    # notes, or any multi-line content.
+    #
+    # @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
+    # @return [String, CANCEL] user input (lines joined with \n) or CANCEL if cancelled
+    def multiline_text(message:, **opts)
+      Prompts::MultilineText.new(message:, **opts).run
+    end
+
     # Prompt for password input (masked display).
     #
     # @param message [String] the prompt message

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clack
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Steve Whittaker
@@ -39,6 +39,7 @@ files:
 - lib/clack/prompts/autocomplete_multiselect.rb
 - lib/clack/prompts/confirm.rb
 - lib/clack/prompts/group_multiselect.rb
+- lib/clack/prompts/multiline_text.rb
 - lib/clack/prompts/multiselect.rb
 - lib/clack/prompts/password.rb
 - lib/clack/prompts/path.rb