clack 0.1.0

data/lib/clack/prompts/select.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Single-selection prompt from a list of options.
+    #
+    # Navigate with arrow keys or j/k (vim-style). Press Enter to confirm.
+    # Supports disabled options, hints, and scrolling for long lists.
+    #
+    # Options can be:
+    # - Strings: `["a", "b", "c"]` (value and label are the same)
+    # - Hashes: `[{value: "a", label: "Option A", hint: "details", disabled: false}]`
+    #
+    # @example Basic usage
+    #   choice = Clack.select(
+    #     message: "Pick a color",
+    #     options: %w[red green blue]
+    #   )
+    #
+    # @example With rich options
+    #   db = Clack.select(
+    #     message: "Choose database",
+    #     options: [
+    #       { value: "pg", label: "PostgreSQL", hint: "recommended" },
+    #       { value: "mysql", label: "MySQL" },
+    #       { value: "sqlite", label: "SQLite", disabled: true }
+    #     ],
+    #     initial_value: "pg",
+    #     max_items: 5
+    #   )
+    #
+    class Select < Core::Prompt
+      include Core::OptionsHelper
+
+      # @param message [String] the prompt message
+      # @param options [Array<Hash, String>] list of options (see class docs)
+      # @param initial_value [Object, nil] value of initially selected option
+      # @param max_items [Integer, nil] max visible items (enables scrolling)
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, options:, initial_value: nil, max_items: nil, **opts)
+        super(message:, **opts)
+        @options = normalize_options(options)
+        @cursor = find_initial_cursor(initial_value)
+        @max_items = max_items
+        @scroll_offset = 0
+        update_value
+      end
+
+      protected
+
+      def handle_key(key)
+        return if terminal_state?
+
+        action = Core::Settings.action?(key)
+
+        case action
+        when :cancel
+          @state = :cancel
+        when :enter
+          submit unless current_option[:disabled]
+        when :up, :left
+          move_cursor(-1)
+        when :down, :right
+          move_cursor(1)
+        end
+      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 << "#{bar}  #{option_display(opt, actual_idx == @cursor)}\n"
+        end
+
+        lines << "#{Colors.gray(Symbols::S_BAR_END)}\n"
+        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
+
+      private
+
+      def move_cursor(delta)
+        super
+        update_value
+      end
+
+      def update_value
+        @value = current_option[:value]
+      end
+
+      def current_option
+        @options[@cursor]
+      end
+
+      def option_display(opt, active)
+        return disabled_option_display(opt) if opt[:disabled]
+        return active_option_display(opt) if active
+
+        inactive_option_display(opt)
+      end
+
+      def disabled_option_display(opt)
+        symbol = Colors.dim(Symbols::S_RADIO_INACTIVE)
+        label = Colors.strikethrough(Colors.dim(opt[:label]))
+        "#{symbol} #{label}"
+      end
+
+      def active_option_display(opt)
+        symbol = Colors.green(Symbols::S_RADIO_ACTIVE)
+        hint = opt[:hint] ? " #{Colors.dim("(#{opt[:hint]})")}" : ""
+        "#{symbol} #{opt[:label]}#{hint}"
+      end
+
+      def inactive_option_display(opt)
+        symbol = Colors.dim(Symbols::S_RADIO_INACTIVE)
+        "#{symbol} #{Colors.dim(opt[:label])}"
+      end
+    end
+  end
+end

data/lib/clack/prompts/select_key.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Quick selection via keyboard shortcuts.
+    #
+    # Each option has an associated key. Pressing that key immediately
+    # selects the option and submits.
+    #
+    # Options format:
+    # - `{ value: "x", label: "Do X", key: "x" }` - explicit key
+    # - `{ value: "create", label: "Create" }` - key defaults to first char
+    #
+    # @example Basic usage
+    #   action = Clack.select_key(
+    #     message: "What to do?",
+    #     options: [
+    #       { value: "create", label: "Create new", key: "c" },
+    #       { value: "open", label: "Open existing", key: "o" },
+    #       { value: "quit", label: "Quit", key: "q" }
+    #     ]
+    #   )
+    #
+    class SelectKey < Core::Prompt
+      # @param message [String] the prompt message
+      # @param options [Array<Hash>] options with :value, :label, and optionally :key, :hint
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, options:, **opts)
+        super(message:, **opts)
+        @options = normalize_options(options)
+        @value = nil
+      end
+
+      protected
+
+      def handle_key(key)
+        return if terminal_state?
+
+        action = Core::Settings.action?(key)
+
+        case action
+        when :cancel
+          @state = :cancel
+        else
+          # Check if key matches any option
+          opt = @options.find { |o| o[:key]&.downcase == key&.downcase }
+          if opt
+            @value = opt[:value]
+            @state = :submit
+          end
+        end
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+
+        @options.each do |opt|
+          lines << "#{bar}  #{option_display(opt)}\n"
+        end
+
+        lines << "#{Colors.gray(Symbols::S_BAR_END)}\n"
+        lines.join
+      end
+
+      def build_final_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+
+        selected = @options.find { |o| o[:value] == @value }
+        label = selected ? selected[:label] : ""
+        display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(label)) : Colors.dim(label)
+        lines << "#{bar}  #{display}\n"
+
+        lines.join
+      end
+
+      private
+
+      def normalize_options(options)
+        options.map do |opt|
+          {
+            value: opt[:value],
+            label: opt[:label] || opt[:value].to_s,
+            key: opt[:key] || opt[:value].to_s[0],
+            hint: opt[:hint]
+          }
+        end
+      end
+
+      def option_display(opt)
+        key_display = Colors.cyan("[#{opt[:key]}]")
+        hint = opt[:hint] ? " #{Colors.dim("(#{opt[:hint]})")}" : ""
+        "#{key_display} #{opt[:label]}#{hint}"
+      end
+    end
+  end
+end

data/lib/clack/prompts/spinner.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Animated spinner for async operations.
+    #
+    # Runs animation in a background thread. Call {#start} to begin,
+    # {#stop}/{#error}/{#cancel} to finish. Thread-safe message updates.
+    #
+    # Indicator modes:
+    # - `:dots` - animating dots after message (default)
+    # - `:timer` - elapsed time display [Xs] or [Xm Ys]
+    #
+    # @example Basic usage
+    #   s = Clack.spinner
+    #   s.start("Installing...")
+    #   # ... do work ...
+    #   s.stop("Done!")
+    #
+    # @example With timer
+    #   s = Clack.spinner(indicator: :timer)
+    #   s.start("Building")
+    #   build_project
+    #   s.stop("Build complete")  # => "Build complete [12s]"
+    #
+    # @example Updating message mid-spin
+    #   s = Clack.spinner
+    #   s.start("Step 1...")
+    #   do_step_1
+    #   s.message("Step 2...")
+    #   do_step_2
+    #   s.stop("All done!")
+    #
+    class Spinner
+      # @param indicator [:dots, :timer] animation style (default: :dots)
+      # @param frames [Array<String>, nil] custom spinner frames
+      # @param delay [Float, nil] delay between frames in seconds
+      # @param style_frame [Proc, nil] proc to style each frame character
+      # @param output [IO] output stream (default: $stdout)
+      def initialize(
+        indicator: :dots,
+        frames: nil,
+        delay: nil,
+        style_frame: nil,
+        output: $stdout
+      )
+        @output = output
+        @indicator = indicator
+        @frames = frames || Symbols::SPINNER_FRAMES
+        @delay = delay || Symbols::SPINNER_DELAY
+        @style_frame = style_frame || ->(frame) { Colors.magenta(frame) }
+        @running = false
+        @cancelled = false
+        @message = ""
+        @thread = nil
+        @frame_idx = 0
+        @dot_idx = 0
+        @prev_frame = nil
+        @start_time = nil
+        @mutex = Mutex.new
+      end
+
+      # Start the spinner animation.
+      #
+      # @param message [String, nil] initial message to display
+      # @return [self] for method chaining
+      def start(message = nil)
+        @mutex.synchronize do
+          return if @running
+
+          @message = remove_trailing_dots(message || "")
+          @running = true
+          @cancelled = false
+          @prev_frame = nil
+          @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @dot_idx = 0
+        end
+
+        @output.print Core::Cursor.hide
+        @output.print "#{Colors.gray(Symbols::S_BAR)}\n"
+
+        @thread = Thread.new { spin_loop }
+        self
+      end
+
+      # Stop with success state.
+      #
+      # @param message [String, nil] final message (uses current if nil)
+      def stop(message = nil)
+        finish(:success, message)
+      end
+
+      # Stop with error state.
+      #
+      # @param message [String, nil] error message (uses current if nil)
+      def error(message = nil)
+        finish(:error, message)
+      end
+
+      # Stop with cancelled state.
+      #
+      # @param message [String, nil] cancellation message
+      def cancel(message = nil)
+        finish(:cancel, message)
+      end
+
+      # Update the spinner message while running.
+      #
+      # @param msg [String] new message to display
+      def message(msg)
+        @mutex.synchronize { @message = remove_trailing_dots(msg) }
+      end
+
+      # Clear the spinner without showing a final message.
+      def clear
+        @mutex.synchronize do
+          @running = false
+        end
+        @thread&.join
+        restore_cursor
+        @output.print Core::Cursor.clear_down
+        @output.print Core::Cursor.show
+      end
+
+      def cancelled?
+        @cancelled
+      end
+
+      private
+
+      def remove_trailing_dots(msg)
+        msg.to_s.sub(/\.+$/, "")
+      end
+
+      def format_timer
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+        min = (elapsed / 60).to_i
+        secs = (elapsed % 60).to_i
+        min.positive? ? "[#{min}m #{secs}s]" : "[#{secs}s]"
+      end
+
+      def spin_loop
+        frame_count = 0
+        while @mutex.synchronize { @running }
+          frame = @style_frame.call(@frames[@frame_idx])
+          msg = @mutex.synchronize { @message }
+          render_frame(frame, msg, frame_count)
+
+          @frame_idx = (@frame_idx + 1) % @frames.length
+          frame_count += 1
+          sleep @delay
+        end
+      end
+
+      def render_frame(frame, msg, frame_count)
+        suffix = case @indicator
+        when :timer
+          " #{format_timer}"
+        when :dots
+          # Animate dots: cycles every 8 frames (0-3 dots)
+          dot_count = (frame_count / 2) % 4
+          "." * dot_count
+        else
+          ""
+        end
+
+        line = "#{frame}  #{msg}#{suffix}"
+        @mutex.synchronize do
+          return if line == @prev_frame
+
+          @output.print "\r#{Core::Cursor.clear_to_end}#{line}"
+          @prev_frame = line
+        end
+      end
+
+      def finish(state, message)
+        msg, timer_suffix = @mutex.synchronize do
+          @running = false
+          suffix = (@indicator == :timer) ? " #{format_timer}" : ""
+          [message || @message, suffix]
+        end
+
+        @thread&.join
+
+        @output.print "\r#{Core::Cursor.clear_to_end}"
+
+        symbol = case state
+        when :success then Colors.green(Symbols::S_STEP_SUBMIT)
+        when :error then Colors.red(Symbols::S_STEP_ERROR)
+        when :cancel
+          @cancelled = true
+          Colors.red(Symbols::S_STEP_CANCEL)
+        end
+
+        @output.print "#{symbol}  #{msg}#{timer_suffix}\n"
+        @output.print Core::Cursor.show
+      end
+
+      def restore_cursor
+        return unless @prev_frame
+
+        @output.print "\r"
+      end
+    end
+  end
+end

data/lib/clack/prompts/tasks.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Sequential task runner with spinner animation.
+    #
+    # Runs tasks in order, showing a spinner while each runs.
+    # Displays success/error status after each task completes.
+    #
+    # Each task is a hash with:
+    # - `:title` - display title
+    # - `:task` - Proc to execute (exceptions are caught)
+    #
+    # @example Basic usage
+    #   results = Clack.tasks(tasks: [
+    #     { title: "Checking dependencies", task: -> { check_deps } },
+    #     { title: "Building project", task: -> { build } },
+    #     { title: "Running tests", task: -> { run_tests } }
+    #   ])
+    #
+    # @example Checking results
+    #   results.each do |r|
+    #     if r.status == :error
+    #       puts "#{r.title} failed: #{r.error}"
+    #     end
+    #   end
+    #
+    class Tasks
+      # @!attribute [r] title
+      #   @return [String] the task title
+      # @!attribute [r] task
+      #   @return [Proc] the task to execute
+      Task = Struct.new(:title, :task, keyword_init: true)
+
+      # @!attribute [r] title
+      #   @return [String] the task title
+      # @!attribute [r] status
+      #   @return [Symbol] :success or :error
+      # @!attribute [r] error
+      #   @return [String, nil] error message if failed
+      TaskResult = Struct.new(:title, :status, :error, keyword_init: true)
+
+      # @param tasks [Array<Hash>] tasks with :title and :task keys
+      # @param output [IO] output stream (default: $stdout)
+      def initialize(tasks:, output: $stdout)
+        @tasks = tasks.map { |task_data| Task.new(title: task_data[:title], task: task_data[:task]) }
+        @output = output
+        @results = []
+        @current_index = 0
+        @frame_index = 0
+        @spinning = false
+        @mutex = Mutex.new
+      end
+
+      # Run all tasks sequentially.
+      #
+      # @return [Array<TaskResult>] results for each task
+      def run
+        @output.print Core::Cursor.hide
+        @tasks.each_with_index do |task, idx|
+          @current_index = idx
+          run_task(task)
+        end
+        @output.print Core::Cursor.show
+        @results
+      end
+
+      private
+
+      def run_task(task)
+        render_pending(task.title)
+
+        begin
+          task.task.call
+          @results << TaskResult.new(title: task.title, status: :success, error: nil)
+          render_success(task.title)
+        rescue => exception
+          @results << TaskResult.new(title: task.title, status: :error, error: exception.message)
+          render_error(task.title, exception.message)
+        end
+      end
+
+      def render_pending(title)
+        @output.print "\r#{Core::Cursor.clear_to_end}"
+        @output.print "#{Colors.magenta(spinner_frame)}  #{title}"
+        @spinner_thread = start_spinner(title)
+      end
+
+      def render_success(title)
+        stop_spinner
+        @output.print "\r#{Core::Cursor.clear_to_end}"
+        @output.puts "#{Colors.green(Symbols::S_STEP_SUBMIT)}  #{title}"
+      end
+
+      def render_error(title, message)
+        stop_spinner
+        @output.print "\r#{Core::Cursor.clear_to_end}"
+        @output.puts "#{Colors.red(Symbols::S_STEP_CANCEL)}  #{title}"
+        @output.puts "#{Colors.gray(Symbols::S_BAR)}  #{Colors.red(message)}"
+      end
+
+      def start_spinner(title)
+        @mutex.synchronize do
+          @spinning = true
+          @frame_index = 0
+        end
+        Thread.new do
+          while @mutex.synchronize { @spinning }
+            frame = @mutex.synchronize do
+              current_frame = Symbols::SPINNER_FRAMES[@frame_index]
+              @frame_index = (@frame_index + 1) % Symbols::SPINNER_FRAMES.length
+              current_frame
+            end
+            @output.print "\r#{Core::Cursor.clear_to_end}"
+            @output.print "#{Colors.magenta(frame)}  #{title}"
+            sleep Symbols::SPINNER_DELAY
+          end
+        end
+      end
+
+      def stop_spinner
+        @mutex.synchronize { @spinning = false }
+        @spinner_thread&.join
+      end
+
+      def spinner_frame
+        @mutex.synchronize { Symbols::SPINNER_FRAMES[@frame_index] }
+      end
+    end
+  end
+end

data/lib/clack/prompts/text.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Single-line text input prompt with cursor navigation.
+    #
+    # Features:
+    # - Arrow key cursor movement (left/right)
+    # - Backspace/delete support
+    # - Placeholder text (shown when empty)
+    # - Default value (used if submitted empty)
+    # - Initial value (pre-filled, editable)
+    # - Validation support
+    #
+    # @example Basic usage
+    #   name = Clack.text(message: "What is your name?")
+    #
+    # @example With all options
+    #   name = Clack.text(
+    #     message: "Project name?",
+    #     placeholder: "my-project",
+    #     default_value: "untitled",
+    #     initial_value: "hello",
+    #     validate: ->(v) { "Required!" if v.empty? }
+    #   )
+    #
+    class Text < Core::Prompt
+      include Core::TextInputHelper
+
+      # @param message [String] the prompt message
+      # @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 proc returning error string or nil
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, placeholder: nil, default_value: nil, initial_value: nil, **opts)
+        super(message:, **opts)
+        @placeholder = placeholder
+        @default_value = default_value
+        @value = initial_value || ""
+        @cursor = @value.grapheme_clusters.length
+      end
+
+      protected
+
+      def handle_input(key, action)
+        # Only use arrow key actions for actual arrow keys, not vim h/l keys
+        # which should be treated as text input
+        if key&.start_with?("\e[")
+          max_cursor = @value.grapheme_clusters.length
+          case action
+          when :left
+            @cursor = [@cursor - 1, 0].max
+            return
+          when :right
+            @cursor = [@cursor + 1, max_cursor].min
+            return
+          end
+        end
+
+        handle_text_input(key)
+      end
+
+      def submit
+        @value = @default_value if @value.empty? && @default_value
+        super
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+        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
+
+        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
+    end
+  end
+end