clack 0.1.0

data/lib/clack/core/cursor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    # ANSI escape sequences for cursor control.
+    # See: https://en.wikipedia.org/wiki/ANSI_escape_code
+    module Cursor
+      class << self
+        # Override enabled state for testing or special cases
+        attr_writer :enabled
+
+        def enabled?
+          return @enabled unless @enabled.nil?
+
+          # Default: check if output supports ANSI escape sequences
+          $stdout.tty? && ENV["TERM"] != "dumb" && !ENV["NO_COLOR"]
+        end
+
+        # Visibility
+        # DECTCEM: Hide cursor
+        def hide = enabled? ? "\e[?25l" : ""
+        # DECTCEM: Show cursor
+        def show = enabled? ? "\e[?25h" : ""
+
+        # Movement (CSI sequences)
+        # CUU: Cursor Up
+        def up(n = 1) = enabled? ? "\e[#{n}A" : ""
+        # CUD: Cursor Down
+        def down(n = 1) = enabled? ? "\e[#{n}B" : ""
+        # CUF: Cursor Forward
+        def forward(n = 1) = enabled? ? "\e[#{n}C" : ""
+        # CUB: Cursor Back
+        def back(n = 1) = enabled? ? "\e[#{n}D" : ""
+
+        # Absolute positioning
+        # CUP: Cursor Position
+        def to(x, y) = enabled? ? "\e[#{y};#{x}H" : ""
+        # CHA: Cursor Horizontal Absolute
+        def column(n) = enabled? ? "\e[#{n}G" : ""
+        # CUP: Home position (1,1)
+        def home = enabled? ? "\e[H" : ""
+
+        # Save/restore
+        # DECSC: Save Cursor Position
+        def save = enabled? ? "\e7" : ""
+        # DECRC: Restore Cursor Position
+        def restore = enabled? ? "\e8" : ""
+
+        # Erasing
+        # EL: Erase entire line
+        def clear_line = enabled? ? "\e[2K" : ""
+        # EL: Erase to end of line
+        def clear_to_end = enabled? ? "\e[K" : ""
+        # ED: Erase below cursor
+        def clear_down = enabled? ? "\e[J" : ""
+        # ED: Erase entire screen
+        def clear_screen = enabled? ? "\e[2J" : ""
+      end
+    end
+  end
+end

data/lib/clack/core/key_reader.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Clack
+  module Core
+    # Reads single keystrokes from the terminal in raw mode.
+    # Handles escape sequences for arrow keys and other special keys.
+    module KeyReader
+      # Timeout for detecting if Escape is part of a sequence (50ms).
+      # If no follow-up character arrives, treat Escape as a standalone key.
+      ESCAPE_TIMEOUT = 0.05
+
+      # Timeout for reading additional characters in a CSI sequence (10ms).
+      # Short because subsequent bytes in a sequence arrive almost instantly.
+      SEQUENCE_TIMEOUT = 0.01
+
+      class << self
+        def read
+          console = IO.console
+          raise IOError, "No console available (not a TTY?)" unless console
+
+          console.raw do |io|
+            char = io.getc
+            return char if char.nil? # EOF
+            return char unless char == "\e"
+
+            # Check for escape sequence - wait briefly for follow-up
+            return char unless IO.select([io], nil, nil, ESCAPE_TIMEOUT)
+
+            seq = io.getc.to_s
+            return "\e#{seq}" unless seq == "["
+
+            # Read CSI sequence until no more characters arrive
+            seq += io.getc.to_s while IO.select([io], nil, nil, SEQUENCE_TIMEOUT)
+            "\e[#{seq[1..]}"
+          end
+        rescue Errno::EIO, Errno::EBADF, IOError
+          # Terminal disconnected or closed - treat as cancel
+          "\u0003" # Ctrl+C
+        end
+      end
+    end
+  end
+end

data/lib/clack/core/options_helper.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    # Shared functionality for option-based prompts (Select, Multiselect).
+    # Handles option normalization, cursor navigation, and scrolling.
+    module OptionsHelper
+      # Normalize options to a consistent hash format.
+      # Accepts strings, symbols, or hashes with value/label/hint/disabled keys.
+      #
+      # @param options [Array] Raw options in various formats
+      # @return [Array<Hash>] Normalized option hashes
+      # @raise [ArgumentError] if options is empty
+      def normalize_options(options)
+        raise ArgumentError, "options cannot be empty" if options.nil? || options.empty?
+
+        options.map do |opt|
+          case opt
+          when Hash
+            {
+              value: opt[:value],
+              label: opt[:label] || opt[:value].to_s,
+              hint: opt[:hint],
+              disabled: opt[:disabled] || false
+            }
+          else
+            {value: opt, label: opt.to_s, hint: nil, disabled: false}
+          end
+        end
+      end
+
+      # Find the next enabled option in the given direction.
+      # Wraps around the list if necessary.
+      #
+      # @param from [Integer] Starting index
+      # @param delta [Integer] Direction (+1 for forward, -1 for backward)
+      # @return [Integer] Index of next enabled option, or from if all disabled
+      def find_next_enabled(from, delta)
+        max = @options.length
+        idx = (from + delta) % max
+
+        max.times do
+          return idx unless @options[idx][:disabled]
+
+          idx = (idx + delta) % max
+        end
+
+        from
+      end
+
+      # Move cursor in the given direction, skipping disabled options.
+      #
+      # @param delta [Integer] Direction (+1 for down/right, -1 for up/left)
+      def move_cursor(delta)
+        @cursor = find_next_enabled(@cursor, delta)
+        update_scroll
+      end
+
+      # Get the currently visible options based on scroll offset and max_items.
+      #
+      # @return [Array<Hash>] Visible options
+      def visible_options
+        return @options unless @max_items && @options.length > @max_items
+
+        @options[@scroll_offset, @max_items]
+      end
+
+      # Update scroll offset to keep cursor visible within the window.
+      def update_scroll
+        return unless @max_items && @options.length > @max_items
+
+        if @cursor < @scroll_offset
+          @scroll_offset = @cursor
+        elsif @cursor >= @scroll_offset + @max_items
+          @scroll_offset = @cursor - @max_items + 1
+        end
+      end
+
+      # Find initial cursor position based on initial value or first enabled option.
+      #
+      # @param initial_value [Object, nil] Initial value to select
+      # @return [Integer] Cursor position
+      def find_initial_cursor(initial_value)
+        return 0 if @options.empty?
+
+        if initial_value.nil?
+          # Start at first enabled option
+          return @options[0][:disabled] ? find_next_enabled(-1, 1) : 0
+        end
+
+        idx = @options.find_index { |o| o[:value] == initial_value }
+        (idx && !@options[idx][:disabled]) ? idx : find_next_enabled(-1, 1)
+      end
+    end
+  end
+end

data/lib/clack/core/prompt.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Clack
+  module Core
+    # Base class for all interactive prompts.
+    #
+    # Implements a state machine with states: :initial, :active, :error, :submit, :cancel.
+    # Subclasses override {#handle_input}, {#build_frame}, and {#build_final_frame}
+    # to customize behavior and rendering.
+    #
+    # The prompt loop:
+    # 1. Renders the initial frame
+    # 2. Reads keyboard input via {KeyReader}
+    # 3. Handles input and transitions state
+    # 4. Re-renders the frame
+    # 5. Repeats until a terminal state (:submit or :cancel)
+    #
+    # @abstract Subclass and override {#build_frame} to implement a prompt.
+    #
+    # @example Creating a custom prompt
+    #   class MyPrompt < Clack::Core::Prompt
+    #     def build_frame
+    #       "#{bar}\n#{symbol_for_state}  #{@message}\n"
+    #     end
+    #   end
+    #
+    class Prompt
+      # @return [Symbol] current state (:initial, :active, :error, :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
+
+      # @param message [String] the prompt message to display
+      # @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)
+        @message = message
+        @validate = validate
+        @input = input
+        @output = output
+        @state = :initial
+        @value = nil
+        @error_message = nil
+        @prev_frame = nil
+        @cursor = 0
+      end
+
+      # Run the prompt interaction loop.
+      #
+      # Sets up the terminal, renders frames, and processes input until the user
+      # submits or cancels. Returns the final value or {Clack::CANCEL}.
+      #
+      # @return [Object, Clack::CANCEL] the submitted value or CANCEL sentinel
+      def run
+        setup_terminal
+        render
+        @state = :active
+
+        loop do
+          key = KeyReader.read
+          handle_key(key)
+          render
+
+          break if terminal_state?
+        end
+
+        finalize
+        (terminal_state? && @state == :cancel) ? CANCEL : @value
+      ensure
+        cleanup_terminal
+      end
+
+      protected
+
+      # Process a keypress and update state accordingly.
+      # Delegates to {#handle_input} for prompt-specific behavior.
+      #
+      # @param key [String] the key code from {KeyReader}
+      def handle_key(key)
+        return if terminal_state?
+
+        @state = :active if @state == :error
+
+        action = Settings.action?(key)
+
+        case action
+        when :cancel
+          @state = :cancel
+        when :enter
+          submit
+        else
+          handle_input(key, action)
+        end
+      end
+
+      # Handle prompt-specific input. Override in subclasses.
+      #
+      # @param key [String] the raw key code
+      # @param action [Symbol, nil] the mapped action (:up, :down, etc.) or nil
+      def handle_input(key, action)
+        # Override in subclasses
+      end
+
+      # Validate and submit the current value.
+      # Sets state to :error if validation fails, :submit otherwise.
+      def submit
+        if @validate
+          result = @validate.call(@value)
+          if result
+            @error_message = result.is_a?(Exception) ? result.message : result.to_s
+            @state = :error
+            return
+          end
+        end
+        @state = :submit
+      end
+
+      # Render the current frame using differential rendering.
+      # Only redraws if the frame content has changed.
+      def render
+        frame = build_frame
+        return if frame == @prev_frame
+
+        if @state == :initial
+          @output.print Cursor.hide
+        else
+          restore_cursor
+        end
+
+        @output.print Cursor.clear_down
+        @output.print frame
+        @prev_frame = frame
+      end
+
+      # Build the frame string for the current state.
+      # Override in subclasses to customize display.
+      #
+      # @return [String] the frame content to render
+      def build_frame
+        # Override in subclasses
+        ""
+      end
+
+      # Render the final frame after submit/cancel.
+      def finalize
+        restore_cursor
+        @output.print Cursor.clear_down
+        @output.print build_final_frame
+      end
+
+      # Build the final frame shown after interaction ends.
+      # Override to show a different view for completed prompts.
+      #
+      # @return [String] the final frame content
+      def build_final_frame
+        build_frame
+      end
+
+      # Check if prompt has reached a terminal state.
+      #
+      # @return [Boolean] true if state is :submit or :cancel
+      def terminal_state?
+        %i[submit cancel].include?(@state)
+      end
+
+      private
+
+      def setup_terminal
+        @output.print Cursor.hide
+      end
+
+      def cleanup_terminal
+        @output.print Cursor.show
+      end
+
+      def restore_cursor
+        return unless @prev_frame
+
+        lines = @prev_frame.count("\n")
+        @output.print Cursor.up(lines) if lines.positive?
+        @output.print Cursor.column(1)
+      end
+
+      def bar
+        Colors.gray(Symbols::S_BAR)
+      end
+
+      def active_bar
+        (@state == :error) ? Colors.yellow(Symbols::S_BAR) : bar
+      end
+
+      def bar_end
+        (@state == :error) ? Colors.yellow(Symbols::S_BAR_END) : Colors.gray(Symbols::S_BAR_END)
+      end
+
+      def cursor_block
+        Colors.inverse(" ")
+      end
+
+      def symbol_for_state
+        case @state
+        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)
+        end
+      end
+    end
+  end
+end

data/lib/clack/core/settings.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    module Settings
+      # Navigation and control actions
+      ACTIONS = %i[up down left right space enter cancel].freeze
+
+      # Key code constants
+      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_ESCAPE = "\e"           # ASCII 27: Escape
+      KEY_ENTER = "\r"            # ASCII 13: Carriage return
+      KEY_NEWLINE = "\n"          # ASCII 10: Line feed
+      KEY_SPACE = " "             # ASCII 32: Space
+
+      # First printable ASCII character (space)
+      PRINTABLE_CHAR_MIN = 32
+
+      # Key to action mappings
+      ALIASES = {
+        "k" => :up,
+        "j" => :down,
+        "h" => :left,
+        "l" => :right,
+        "\e[A" => :up,
+        "\e[B" => :down,
+        "\e[C" => :right,
+        "\e[D" => :left,
+        KEY_ENTER => :enter,
+        KEY_NEWLINE => :enter,
+        KEY_SPACE => :space,
+        KEY_ESCAPE => :cancel,
+        KEY_CTRL_C => :cancel
+      }.freeze
+
+      # Global configuration (mutable)
+      @config = {
+        aliases: ALIASES.dup,
+        with_guide: true
+      }
+      @config_mutex = Mutex.new
+
+      class << self
+        # Get a copy of the current global config
+        # @return [Hash] Current configuration
+        def config
+          @config_mutex.synchronize { @config.dup }
+        end
+
+        # Update global settings
+        # @param aliases [Hash, nil] Custom key to action mappings (merged with defaults)
+        # @param with_guide [Boolean, nil] Whether to show guide bars
+        # @return [Hash] Updated configuration
+        def update(aliases: nil, with_guide: nil)
+          @config_mutex.synchronize do
+            @config[:aliases] = ALIASES.merge(aliases) if aliases
+            @config[:with_guide] = with_guide unless with_guide.nil?
+            @config.dup
+          end
+        end
+
+        # Reset settings to defaults
+        def reset!
+          @config_mutex.synchronize do
+            @config = {
+              aliases: ALIASES.dup,
+              with_guide: true
+            }
+          end
+        end
+
+        # Check if guide bars should be shown
+        # @return [Boolean]
+        def with_guide?
+          @config_mutex.synchronize { @config[:with_guide] }
+        end
+
+        def action?(key)
+          aliases = @config_mutex.synchronize { @config[:aliases] }
+          aliases[key] if ACTIONS.include?(aliases[key])
+        end
+
+        # Check if a key is a printable character
+        def printable?(key)
+          key && key.length == 1 && key.ord >= PRINTABLE_CHAR_MIN
+        end
+
+        # Check if a key is a backspace/delete
+        def backspace?(key)
+          [KEY_BACKSPACE, KEY_DELETE].include?(key)
+        end
+      end
+    end
+  end
+end

data/lib/clack/core/text_input_helper.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    # Shared functionality for text input prompts (Text, Autocomplete, Path).
+    # Handles cursor display, placeholder rendering, and text manipulation.
+    module TextInputHelper
+      # Display the input field with cursor or placeholder.
+      #
+      # @return [String] Formatted input display
+      def input_display
+        return placeholder_display if @value.empty?
+
+        value_with_cursor
+      end
+
+      # Display placeholder with cursor on first character.
+      # Override @placeholder in including class to customize.
+      #
+      # @return [String] Formatted placeholder
+      def placeholder_display
+        text = current_placeholder
+        return cursor_block if text.nil? || text.empty?
+
+        format_placeholder_with_cursor(text)
+      end
+
+      def current_placeholder
+        defined?(@placeholder) ? @placeholder : nil
+      end
+
+      def format_placeholder_with_cursor(text)
+        chars = text.grapheme_clusters
+        first = chars.first || ""
+        rest = chars[1..].join
+        "#{Colors.inverse(first)}#{Colors.dim(rest)}"
+      end
+
+      # Display value with inverse cursor at current position.
+      # Uses grapheme clusters for proper Unicode handling (e.g., emoji).
+      #
+      # @return [String] Value with cursor
+      def value_with_cursor
+        chars = @value.grapheme_clusters
+        return "#{@value}#{cursor_block}" if @cursor >= chars.length
+
+        before = chars[0...@cursor].join
+        current = Colors.inverse(chars[@cursor])
+        after = chars[(@cursor + 1)..].join
+        "#{before}#{current}#{after}"
+      end
+
+      # Handle text input key (backspace/delete or printable character).
+      # Requires @value and @cursor instance variables.
+      # Uses grapheme clusters for proper Unicode handling.
+      #
+      # @param key [String] The key pressed
+      # @return [Boolean] true if input was handled
+      def handle_text_input(key)
+        return handle_backspace if Core::Settings.backspace?(key)
+        return false unless Core::Settings.printable?(key)
+
+        chars = @value.grapheme_clusters
+        chars.insert(@cursor, key)
+        @value = chars.join
+        @cursor += 1
+        true
+      end
+
+      private
+
+      def handle_backspace
+        return false if @cursor.zero?
+
+        chars = @value.grapheme_clusters
+        chars.delete_at(@cursor - 1)
+        @value = chars.join
+        @cursor -= 1
+        true
+      end
+    end
+  end
+end