clack 0.1.0

data/lib/clack/prompts/multiselect.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Multiple-selection prompt from a list of options.
+    #
+    # Navigate with arrow keys or j/k. Toggle selection with Space.
+    # Supports shortcuts: 'a' to toggle all, 'i' to invert selection.
+    #
+    # Options format is the same as {Select}.
+    #
+    # @example Basic usage
+    #   features = Clack.multiselect(
+    #     message: "Select features",
+    #     options: %w[api auth admin]
+    #   )
+    #
+    # @example With options and validation
+    #   features = Clack.multiselect(
+    #     message: "Select features",
+    #     options: [
+    #       { value: "api", label: "API Mode" },
+    #       { value: "auth", label: "Authentication" }
+    #     ],
+    #     initial_values: ["api"],
+    #     required: true,
+    #     max_items: 5
+    #   )
+    #
+    class Multiselect < Core::Prompt
+      include Core::OptionsHelper
+
+      # @param message [String] the prompt message
+      # @param options [Array<Hash, String>] list of options
+      # @param initial_values [Array] values to pre-select
+      # @param required [Boolean] require at least one selection (default: true)
+      # @param max_items [Integer, nil] max visible items (enables scrolling)
+      # @param cursor_at [Object, nil] value to position cursor at initially
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, options:, initial_values: [], required: true, max_items: nil, cursor_at: nil, **opts)
+        super(message:, **opts)
+        @options = normalize_options(options)
+        @selected = Set.new(initial_values)
+        @required = required
+        @max_items = max_items
+        @scroll_offset = 0
+        @cursor = find_initial_cursor(cursor_at)
+        update_value
+      end
+
+      protected
+
+      def handle_key(key)
+        return if terminal_state?
+
+        @state = :active if @state == :error
+        action = Core::Settings.action?(key)
+
+        case action
+        when :cancel
+          @state = :cancel
+        when :enter
+          submit
+        when :up
+          move_cursor(-1)
+        when :down
+          move_cursor(1)
+        when :space
+          toggle_current
+        else
+          handle_char(key)
+        end
+      end
+
+      def handle_char(key)
+        case key&.downcase
+        when "a"
+          toggle_all
+        when "i"
+          invert_selection
+        end
+      end
+
+      def submit
+        if @required && @selected.empty?
+          @error_message = "Please select at least one option.\nPress #{Colors.cyan("space")} to select, #{Colors.cyan("enter")} to submit"
+          @state = :error
+          return
+        end
+        super
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+
+        visible_options.each_with_index do |opt, idx|
+          actual_idx = @scroll_offset + idx
+          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
+
+        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
+      end
+
+      private
+
+      def toggle_current
+        opt = @options[@cursor]
+        return if opt[:disabled]
+
+        if @selected.include?(opt[:value])
+          @selected.delete(opt[:value])
+        else
+          @selected.add(opt[:value])
+        end
+        update_value
+      end
+
+      def toggle_all
+        enabled = @options.reject { |o| o[:disabled] }.map { |o| o[:value] }
+        if enabled.all? { |v| @selected.include?(v) }
+          @selected.clear
+        else
+          @selected.merge(enabled)
+        end
+        update_value
+      end
+
+      def invert_selection
+        @options.each do |opt|
+          next if opt[:disabled]
+
+          if @selected.include?(opt[:value])
+            @selected.delete(opt[:value])
+          else
+            @selected.add(opt[:value])
+          end
+        end
+        update_value
+      end
+
+      def update_value
+        @value = @selected.to_a
+      end
+
+      def option_display(opt, idx)
+        active = idx == @cursor
+        selected = @selected.include?(opt[:value])
+
+        symbol, label = option_parts(opt, active, selected)
+        "#{symbol} #{label}"
+      end
+
+      def option_parts(opt, active, selected)
+        if opt[:disabled]
+          return [Colors.dim(Symbols::S_CHECKBOX_INACTIVE),
+            Colors.strikethrough(Colors.dim(opt[:label]))]
+        end
+        return [Colors.green(Symbols::S_CHECKBOX_SELECTED), opt[:label]] if active && selected
+        return [Colors.cyan(Symbols::S_CHECKBOX_ACTIVE), opt[:label]] if active
+        return [Colors.green(Symbols::S_CHECKBOX_SELECTED), Colors.dim(opt[:label])] if selected
+
+        [Colors.dim(Symbols::S_CHECKBOX_INACTIVE), Colors.dim(opt[:label])]
+      end
+    end
+  end
+end

data/lib/clack/prompts/password.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Password input prompt with masked display.
+    #
+    # Displays a mask character for each input character, hiding the actual
+    # password. Supports backspace but not cursor movement (for security).
+    #
+    # @example Basic usage
+    #   secret = Clack.password(message: "Enter your API key")
+    #
+    # @example With custom mask
+    #   secret = Clack.password(message: "Password", mask: "*")
+    #
+    class Password < Core::Prompt
+      # @param message [String] the prompt message
+      # @param mask [String, nil] character to display (default: "▪")
+      # @param validate [Proc, nil] validation proc returning error string or nil
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, mask: nil, **opts)
+        super(message:, **opts)
+        @mask = mask || Symbols::S_PASSWORD_MASK
+        @value = ""
+      end
+
+      protected
+
+      def handle_input(key, _action)
+        return unless Core::Settings.printable?(key)
+
+        if Core::Settings.backspace?(key)
+          @value = @value.chop
+        else
+          @value += key
+        end
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+        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
+
+        lines.join
+      end
+
+      def build_final_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+
+        masked = @mask * @value.length
+        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(masked)) : Colors.dim(masked)
+        lines << "#{bar}  #{display}\n"
+
+        lines.join
+      end
+
+      private
+
+      def masked_display
+        masked = @mask * @value.length
+        return cursor_block if masked.empty?
+
+        "#{masked}#{cursor_block}"
+      end
+
+      def cursor_block
+        Colors.inverse(Colors.hidden("_"))
+      end
+    end
+  end
+end

data/lib/clack/prompts/path.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # File/directory path selector with filesystem navigation.
+    #
+    # Type to filter suggestions from the current directory.
+    # Press Tab to autocomplete the selected suggestion.
+    # Navigate suggestions with arrow keys.
+    #
+    # Supports:
+    # - Absolute paths (starting with /)
+    # - Home directory expansion (~/...)
+    # - Relative paths (from root directory)
+    # - Directory-only filtering
+    #
+    # @example Basic usage
+    #   path = Clack.path(message: "Select a file")
+    #
+    # @example Directory picker
+    #   dir = Clack.path(
+    #     message: "Choose project directory",
+    #     only_directories: true,
+    #     root: "~/projects"
+    #   )
+    #
+    class Path < Core::Prompt
+      include Core::TextInputHelper
+
+      # @param message [String] the prompt message
+      # @param root [String] starting/base directory (default: ".")
+      # @param only_directories [Boolean] only show directories (default: false)
+      # @param max_items [Integer] max visible suggestions (default: 5)
+      # @param validate [Proc, nil] validation proc for the final path
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, root: ".", only_directories: false, max_items: 5, **opts)
+        super(message:, **opts)
+        @root = File.expand_path(root)
+        @only_directories = only_directories
+        @max_items = max_items
+        @value = ""
+        @cursor = 0
+        @selected_index = 0
+        @scroll_offset = 0
+        @suggestions = []
+        update_suggestions
+      end
+
+      protected
+
+      def handle_key(key)
+        return if terminal_state?
+
+        @state = :active if @state == :error
+        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
+          # Tab to autocomplete
+          if key == "\t" && !@suggestions.empty?
+            autocomplete_selection
+          else
+            handle_text_input(key)
+          end
+        end
+      end
+
+      def handle_text_input(key)
+        return unless super
+
+        @selected_index = 0
+        @scroll_offset = 0
+        update_suggestions
+      end
+
+      def autocomplete_selection
+        return if @suggestions.empty?
+
+        @value = @suggestions[@selected_index]
+        @cursor = @value.length
+        update_suggestions
+      end
+
+      def submit_selection
+        path = @value.empty? ? @root : resolve_path(@value)
+
+        if @validate
+          result = @validate.call(path)
+          if result
+            @error_message = result.is_a?(Exception) ? result.message : result.to_s
+            @state = :error
+            return
+          end
+        end
+
+        @value = path
+        @state = :submit
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+        lines << "#{active_bar}  #{input_display}\n"
+
+        visible_suggestions.each_with_index do |path, idx|
+          actual_idx = @scroll_offset + idx
+          lines << "#{bar}  #{suggestion_display(path, actual_idx == @selected_index)}\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"
+
+        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(@value)) : Colors.dim(@value)
+        lines << "#{bar}  #{display}\n"
+
+        lines.join
+      end
+
+      private
+
+      def update_suggestions
+        base_path = resolve_path(@value)
+        search_dir = File.directory?(base_path) ? base_path : File.dirname(base_path)
+        prefix = File.directory?(base_path) ? "" : File.basename(base_path).downcase
+
+        @suggestions = list_entries(search_dir, prefix)
+      rescue SystemCallError
+        @suggestions = []
+      end
+
+      def list_entries(dir, prefix)
+        return [] unless File.directory?(dir)
+
+        entries = Dir.entries(dir) - [".", ".."]
+        entries = entries.select { |entry| File.directory?(File.join(dir, entry)) } if @only_directories
+        entries = entries.select { |entry| entry.downcase.start_with?(prefix) } unless prefix.empty?
+        entries.sort.first(@max_items * 2).map { |entry| format_entry(dir, entry) }
+      end
+
+      def format_entry(dir, entry)
+        full_path = File.join(dir, entry)
+        if full_path.start_with?(@root)
+          # Show relative path without leading ./
+          path = full_path[@root.length..]
+          path = path.sub(%r{^/}, "") # Remove leading slash
+          path = entry if path.empty?
+        else
+          path = full_path
+        end
+        path += "/" if File.directory?(full_path)
+        path
+      end
+
+      def resolve_path(input)
+        return @root if input.empty?
+
+        if input.start_with?("/")
+          input
+        elsif input.start_with?("~")
+          File.expand_path(input)
+        else
+          File.join(@root, input)
+        end
+      end
+
+      def visible_suggestions
+        return @suggestions if @suggestions.length <= @max_items
+
+        @suggestions[@scroll_offset, @max_items]
+      end
+
+      def move_selection(delta)
+        return if @suggestions.empty?
+
+        @selected_index = (@selected_index + delta) % @suggestions.length
+        update_scroll
+      end
+
+      def update_scroll
+        return unless @suggestions.length > @max_items
+
+        if @selected_index < @scroll_offset
+          @scroll_offset = @selected_index
+        elsif @selected_index >= @scroll_offset + @max_items
+          @scroll_offset = @selected_index - @max_items + 1
+        end
+      end
+
+      # Override to use @root as placeholder
+      def placeholder_display
+        return "" if @root.empty?
+
+        first = Colors.inverse(@root[0])
+        rest = Colors.dim(@root[1..])
+        "#{first}#{rest}"
+      end
+
+      def suggestion_display(path, active)
+        icon = path.end_with?("/") ? Symbols::S_FOLDER : Symbols::S_FILE
+        if active
+          "#{Colors.cyan(icon)} #{path}"
+        else
+          "#{Colors.dim(icon)} #{Colors.dim(path)}"
+        end
+      end
+    end
+  end
+end

data/lib/clack/prompts/progress.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Visual progress bar for measurable operations.
+    #
+    # Shows a filled/empty bar with percentage. Call {#start} to begin,
+    # {#advance} or {#update} to show progress, {#stop} to complete.
+    #
+    # @example Basic usage
+    #   progress = Clack.progress(total: 100, message: "Downloading...")
+    #   progress.start
+    #   100.times { |i| progress.update(i + 1) }
+    #   progress.stop("Download complete!")
+    #
+    # @example With advance
+    #   progress = Clack.progress(total: files.size)
+    #   progress.start("Processing files")
+    #   files.each do |file|
+    #     process(file)
+    #     progress.advance  # increments by 1
+    #   end
+    #   progress.stop("Done!")
+    #
+    class Progress
+      # @param total [Integer] total number of steps (must be non-negative)
+      # @param message [String, nil] initial message to display
+      # @param output [IO] output stream (default: $stdout)
+      # @raise [ArgumentError] if total is negative
+      def initialize(total:, message: nil, output: $stdout)
+        raise ArgumentError, "total must be non-negative" if total.negative?
+
+        @total = total
+        @current = 0
+        @message = message
+        @output = output
+        @started = false
+        @rendered_once = false
+        @width = 40
+      end
+
+      # Start displaying the progress bar.
+      #
+      # @param message [String, nil] optional message to display
+      # @return [self] for method chaining
+      def start(message = nil)
+        @message = message if message
+        @started = true
+        render
+        self
+      end
+
+      # Advance progress by the given amount.
+      #
+      # @param amount [Integer] steps to advance (default: 1)
+      # @return [self] for method chaining
+      def advance(amount = 1)
+        @current = [@current + amount, @total].min
+        render
+        self
+      end
+
+      # Set progress to an absolute value.
+      #
+      # @param current [Integer] current progress value
+      # @return [self] for method chaining
+      def update(current)
+        @current = [current, @total].min
+        render
+        self
+      end
+
+      # Update the message without changing progress.
+      #
+      # @param msg [String] new message
+      # @return [self] for method chaining
+      def message(msg)
+        @message = msg
+        render
+        self
+      end
+
+      # Complete with success. Sets progress to 100%.
+      #
+      # @param final_message [String, nil] final message to display
+      # @return [self] for method chaining
+      def stop(final_message = nil)
+        @current = @total
+        @message = final_message if final_message
+        render_final(:success)
+        self
+      end
+
+      # Complete with error state.
+      #
+      # @param message [String, nil] error message
+      # @return [self] for method chaining
+      def error(message = nil)
+        @message = message if message
+        render_final(:error)
+        self
+      end
+
+      private
+
+      def render
+        return unless @started
+
+        # Move cursor up and clear line if not first render
+        if @rendered_once
+          @output.print "\e[1A\e[2K"
+        end
+        @rendered_once = true
+        @output.puts "#{symbol}  #{progress_bar} #{percentage}#{message_text}"
+      end
+
+      def render_final(state)
+        # Move up and clear the progress line
+        @output.print "\e[1A\e[2K" if @rendered_once
+        sym = (state == :success) ? Colors.green(Symbols::S_STEP_SUBMIT) : Colors.red(Symbols::S_STEP_CANCEL)
+        @output.puts "#{sym}  #{@message}"
+      end
+
+      def symbol
+        Colors.cyan(Symbols::S_STEP_ACTIVE)
+      end
+
+      def progress_bar
+        filled = @total.zero? ? @width : (@current.to_f / @total * @width).round
+        empty = @width - filled
+        bar = Colors.green(Symbols::S_PROGRESS_FILLED * filled) + Colors.gray(Symbols::S_PROGRESS_EMPTY * empty)
+        "[#{bar}]"
+      end
+
+      def percentage
+        pct = @total.zero? ? 100 : (@current.to_f / @total * 100).round
+        Colors.dim("#{pct.to_s.rjust(3)}%")
+      end
+
+      def message_text
+        @message ? "  #{@message}" : ""
+      end
+    end
+  end
+end