clack 0.6.1 → 0.7.0

data/lib/clack/prompts/group_multiselect.rb

@@ -33,11 +33,21 @@ module Clack
     #     group_spacing: 1
     #   )
     #
+    # @example Hash shorthand (group label => value => label)
+    #   addons = Clack.group_multiselect(
+    #     message: "Add-ons",
+    #     options: {
+    #       "Observability" => { prom: "Prometheus", dd: "Datadog" },
+    #       "Storage" => %w[s3 gcs]
+    #     }
+    #   )
+    #
     class GroupMultiselect < Core::Prompt
       include Core::SelectionManager
 
       # @param message [String] the prompt message
-      # @param options [Array<Hash>] groups, each with :label and :options (Array<Hash, String>)
+      # @param options [Array<Hash>, Hash] groups as an Array of {label:, options:} hashes, or a Hash of
+      #   group label => options; each group's options accept every shape {Select} accepts (Array or Hash)
       # @param initial_values [Array] values to pre-select
       # @param required [Boolean] require at least one selection (default: true)
       # @param selectable_groups [Boolean] allow toggling all options in a group at once (default: false)
@@ -86,10 +96,7 @@ module Clack
       end
 
       def build_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-        lines << help_line
+        lines = [frame_header]
 
         prev_was_group = false
         @flat_items.each_with_index do |item, idx|
@@ -97,9 +104,7 @@ module Clack
           is_last_in_group = item.is_a?(Core::GroupOption) ? item.last_in_group : false
 
           # Add group spacing before groups (except first)
-          if is_group && !prev_was_group && idx.positive? && @group_spacing.positive?
-            @group_spacing.times { lines << "#{active_bar}\n" }
-          end
+          lines.concat(group_spacing_lines) if is_group && !prev_was_group && idx.positive?
 
           lines << if is_group
             group_display(item, idx == @option_index)
@@ -110,10 +115,7 @@ module Clack
           prev_was_group = is_group
         end
 
-        lines << "#{bar_end}\n"
-
-        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
-
+        lines << frame_footer
         lines.join
       end
 
@@ -121,17 +123,22 @@ module Clack
 
       private
 
-      def normalize_groups(options) = options.map { |group| normalize_group(group) }
+      def normalize_groups(options)
+        return options.map { |label, opts| normalize_group(label: label.to_s, options: opts) } if options.is_a?(Hash)
 
-      def normalize_group(group)
-        {
-          label: group[:label] || group[:group],
-          options: group[:options].map { |opt| normalize_option(opt) }
-        }
+        options.map { |group| normalize_group(group) }
       end
 
-      def normalize_option(opt)
-        Core::OptionsHelper.normalize_option(opt)
+      def normalize_group(group)
+        label = group[:label] || group[:group]
+        opts = group[:options]
+        # Duck-typed on purpose: any Enumerable (Set, Range) worked before the
+        # guard existed and still does; the message names the documented shapes.
+        unless opts.respond_to?(:map)
+          raise ArgumentError, "group #{label.inspect} options must be an Array or Hash"
+        end
+
+        {label: label, options: Core::OptionsHelper.normalize_list(opts)}
       end
 
       def build_flat_items = @groups.flat_map { |group| flatten_group(group) }
@@ -215,14 +222,31 @@ module Clack
 
       def update_value = update_selection_value
 
+      # Blank rail lines between groups; plain newlines when guides are off (upstream behavior).
+      def group_spacing_lines
+        return [] unless @group_spacing.positive?
+
+        line = guide? ? "#{active_bar}\n" : "\n"
+        Array.new(@group_spacing, line)
+      end
+
+      # Shares upstream MULTISELECT_INSTRUCTIONS with Multiselect.
+      def keyboard_hints
+        [
+          key_hint(Symbols::S_ARROWS_UP_DOWN, "to navigate"),
+          key_hint("Space:", "select"),
+          key_hint("Enter:", "confirm")
+        ]
+      end
+
       def group_display(item, active)
         if @selectable_groups
           all_selected = item.options.reject { |o| o.disabled }.all? { |o| @selected.include?(o.value) }
           checkbox = all_selected ? Colors.green(Symbols::S_CHECKBOX_SELECTED) : Colors.dim(Symbols::S_CHECKBOX_INACTIVE)
           label = active ? item.label : Colors.dim(item.label)
-          "#{active_bar}  #{checkbox} #{label}\n"
+          "#{gutter(active_bar)}#{checkbox} #{label}\n"
         else
-          "#{active_bar}  #{Colors.dim(item.label)}\n"
+          "#{gutter(active_bar)}#{Colors.dim(item.label)}\n"
         end
       end
 
@@ -236,15 +260,15 @@ module Clack
         hint = (item.hint && active) ? " #{Colors.dim("(#{item.hint})")}" : ""
 
         if item.disabled
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.strikethrough(Colors.dim(item.label))}\n"
+          "#{gutter(active_bar)}#{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.strikethrough(Colors.dim(item.label))}\n"
         elsif active && selected
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{item.label}#{hint}\n"
+          "#{gutter(active_bar)}#{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{item.label}#{hint}\n"
         elsif active
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.cyan(Symbols::S_CHECKBOX_ACTIVE)} #{item.label}#{hint}\n"
+          "#{gutter(active_bar)}#{Colors.dim(prefix)}#{Colors.cyan(Symbols::S_CHECKBOX_ACTIVE)} #{item.label}#{hint}\n"
         elsif selected
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{Colors.dim(item.label)}\n"
+          "#{gutter(active_bar)}#{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{Colors.dim(item.label)}\n"
         else
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.dim(item.label)}\n"
+          "#{gutter(active_bar)}#{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.dim(item.label)}\n"
         end
       end
     end

data/lib/clack/prompts/multiline_text.rb

@@ -25,7 +25,7 @@ module Clack
 
       # @param message [String] the prompt message
       # @param initial_value [String, nil] pre-filled editable text (can contain newlines)
-      # @option opts [Proc, nil] :validate validation proc returning error string or nil
+      # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve})
       # @option opts [Hash] additional options passed to {Core::Prompt}
       def initialize(message:, initial_value: nil, **opts)
         super(message:, **opts)
@@ -67,13 +67,13 @@ module Clack
       end
 
       def frame_header
-        "#{bar}\n#{symbol_for_state}  #{@message} #{Colors.dim("(Ctrl+D to submit)")}\n#{help_line}"
+        "#{guide_line}#{symbol_for_state}  #{@message} #{Colors.dim("(Ctrl+D to submit)")}\n#{help_line}"
       end
 
       def build_frame
         body = @lines.each_with_index.map do |line, idx|
           display = (idx == @line_index) ? value_with_cursor : line
-          "#{active_bar}  #{display}\n"
+          "#{gutter(active_bar)}#{display}\n"
         end.join
 
         "#{frame_header}#{body}#{frame_footer}"
@@ -81,13 +81,13 @@ module Clack
 
       def build_final_frame
         lines = []
-        lines << "#{bar}\n"
+        lines << guide_line
         lines << "#{symbol_for_state}  #{@message}\n"
 
         if @state == :cancel
-          @lines.each { |line| lines << "#{bar}  #{Colors.strikethrough(Colors.dim(line))}\n" }
+          @lines.each { |line| lines << "#{gutter}#{Colors.strikethrough(Colors.dim(line))}\n" }
         else
-          @lines.each { |line| lines << "#{bar}  #{Colors.dim(line)}\n" }
+          @lines.each { |line| lines << "#{gutter}#{Colors.dim(line)}\n" }
         end
 
         lines.join

data/lib/clack/prompts/multiselect.rb

@@ -5,7 +5,8 @@ module Clack
     # 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.
+    # Supports shortcuts: `a` to toggle all, `i` to invert selection (not
+    # listed in the footer; see the README).
     #
     # Options format is the same as {Select}.
     #
@@ -32,7 +33,7 @@ module Clack
       include Core::SelectionManager
 
       # @param message [String] the prompt message
-      # @param options [Array<Hash, String>] list of options
+      # @param options [Array<Hash, String>, Hash] list of options, or a Hash of value => label
       # @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)
@@ -84,23 +85,14 @@ module Clack
       end
 
       def build_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-        lines << help_line
+        lines = [frame_header]
 
         visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx
-          lines << "#{active_bar}  #{option_display(opt, actual_idx)}\n"
-        end
-
-        if @state in :error | :warning
-          lines.concat(validation_message_lines)
-        else
-          lines << "#{bar}  #{keyboard_hints}\n"
-          lines << "#{bar_end}\n"
+          lines << "#{gutter(active_bar)}#{option_display(opt, actual_idx)}\n"
         end
 
+        lines << frame_footer
         lines.join
       end
 
@@ -135,13 +127,14 @@ module Clack
         update_selection_value
       end
 
+      # Upstream MULTISELECT_INSTRUCTIONS; a/i are documented, not listed, so the
+      # line stays narrow enough not to soft-wrap in a split pane.
       def keyboard_hints
-        hints = [
-          "#{Colors.dim("space")} select",
-          "#{Colors.dim("a")} all",
-          "#{Colors.dim("i")} invert"
+        [
+          key_hint(Symbols::S_ARROWS_UP_DOWN, "to navigate"),
+          key_hint("Space:", "select"),
+          key_hint("Enter:", "confirm")
         ]
-        Colors.dim(hints.join(Colors.dim(" / ")))
       end
 
       def option_display(opt, idx)

data/lib/clack/prompts/password.rb

@@ -16,7 +16,7 @@ module Clack
     class Password < Core::Prompt
       # @param message [String] the prompt message
       # @param mask [String, nil] character to display (default: "▪")
-      # @option opts [Proc, nil] :validate validation proc returning error string or nil
+      # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve})
       # @option opts [Hash] additional options passed to {Core::Prompt}
       def initialize(message:, mask: nil, **opts)
         super(message:, **opts)
@@ -35,7 +35,7 @@ module Clack
       end
 
       def build_frame
-        "#{frame_header}#{active_bar}  #{masked_display}\n#{frame_footer}"
+        "#{frame_header}#{gutter(active_bar)}#{masked_display}\n#{frame_footer}"
       end
 
       def final_display = @mask * @value.grapheme_clusters.length

data/lib/clack/prompts/path.rb

@@ -32,7 +32,8 @@ module Clack
       # @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)
-      # @option opts [Proc, nil] :validate validation proc for the final path
+      # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator for the final path
+      #   (see {Validators.resolve})
       # @option opts [Hash] additional options passed to {Core::Prompt}
       def initialize(message:, root: ".", only_directories: false, max_items: 5, **opts)
         super(message:, **opts)
@@ -104,14 +105,24 @@ module Clack
       def build_frame
         suggestion_lines = visible_options.each_with_index.map do |path, idx|
           actual_idx = @scroll_offset + idx
-          "#{bar}  #{suggestion_display(path, actual_idx == @option_index)}\n"
+          "#{gutter(active_bar)}#{suggestion_display(path, actual_idx == @option_index)}\n"
         end.join
 
-        "#{frame_header}#{active_bar}  #{input_display}\n#{suggestion_lines}#{frame_footer}"
+        "#{frame_header}#{gutter(active_bar)}#{input_display}\n#{suggestion_lines}#{frame_footer}"
       end
 
       private
 
+      # Upstream autocomplete footer, completeOnTab variant (Ruby always completes on Tab).
+      def keyboard_hints
+        [
+          key_hint(Symbols::S_ARROWS_UP_DOWN, "to select"),
+          key_hint("Tab:", "complete"),
+          key_hint("Enter:", "confirm"),
+          key_hint("Type:", "to search")
+        ]
+      end
+
       def update_suggestions
         base_path = resolve_path(@value)
 

data/lib/clack/prompts/range.rb

@@ -17,6 +17,9 @@ module Clack
     #     step: 1, initial_value: 4
     #   )
     #
+    # @example Fractional step
+    #   opacity = Clack.range(message: "Opacity", min: 0, max: 1, step: 0.1)
+    #
     class Range < Core::Prompt
       TRACK_WIDTH = 30
       TRACK_CHAR = "\u2501" # ━ (box drawings heavy horizontal)
@@ -25,7 +28,10 @@ module Clack
       # @param message [String] the prompt message
       # @param min [Numeric] minimum value (default: 0)
       # @param max [Numeric] maximum value (default: 100)
-      # @param step [Numeric] increment size (default: 1)
+      # @param step [Numeric] increment size (default: 1). Fractional steps such
+      #   as 0.1 are snapped exactly (0.1 + 0.1 + 0.1 is 0.3, never 0.30000000000000004).
+      #   The prompt returns an Integer when min and step are both Integers,
+      #   a Float when either is a Float, and a Rational for Rational inputs.
       # @param initial_value [Numeric, nil] initial value (defaults to min)
       # @param default [Numeric, nil] deprecated alias for initial_value
       # @param opts [Hash] additional options passed to {Core::Prompt}
@@ -38,6 +44,13 @@ module Clack
         @min = min
         @max = max
         @step = step
+        # Snap arithmetic runs on these exact decimal forms (0.1 => 1/10) so
+        # repeated steps never accumulate binary Float error.
+        @exact_min = exact(min)
+        @exact_step = exact(step)
+        # Whether `min + step` promotes to Float, which decides how grid_value
+        # converts back. Fixed for the life of the prompt, so computed once.
+        @float_grid = (min + step).is_a?(Float)
         @value = clamp(initial_value || default || min)
       end
 
@@ -51,7 +64,7 @@ module Clack
       end
 
       def build_frame
-        "#{frame_header}#{active_bar}  #{slider_display}\n#{frame_footer}"
+        "#{frame_header}#{gutter(active_bar)}#{slider_display}\n#{frame_footer}"
       end
 
       def final_display = format_value(@value)
@@ -62,10 +75,30 @@ module Clack
         @value = clamp(@value + delta)
       end
 
+      # Clamp to [min, max] and snap to the nearest point on the step grid.
+      # The grid position is computed in Rational so a step of 0.1 lands on
+      # 0.3, not 0.30000000000000004, then converted back to the caller's type.
       def clamp(val)
         val = val.clamp(@min, @max)
-        snapped = @min + (((val - @min).to_f / @step).round * @step)
-        snapped.clamp(@min, @max)
+        steps = ((exact(val) - @exact_min) / @exact_step).round
+        grid_value(steps).clamp(@min, @max)
+      end
+
+      # Exact decimal form of a numeric. Floats go through #rationalize so
+      # 0.1 becomes 1/10 rather than its binary approximation; every other
+      # Numeric converts losslessly with #to_r.
+      def exact(num)
+        num.is_a?(Float) ? num.rationalize : num.to_r
+      end
+
+      # Value at grid position `steps`, in the type `min + step` promotes to.
+      # Float grids take the exact Rational and round once at the end. Every
+      # other numeric (Integer, Rational, BigDecimal) is exact under plain
+      # arithmetic, so the caller's own `min + n * step` is used unchanged.
+      def grid_value(steps)
+        return (@exact_min + (steps * @exact_step)).to_f if @float_grid
+
+        @min + (steps * @step)
       end
 
       def format_value(val)

data/lib/clack/prompts/select.rb

@@ -10,6 +10,8 @@ module Clack
     # Options can be:
     # - Strings: `["a", "b", "c"]` (value and label are the same)
     # - Hashes: `[{value: "a", label: "Option A", hint: "details", disabled: false}]`
+    # - A Hash: `{ a: "Option A", b: { label: "Option B", hint: "details", disabled: false } }`
+    #   (keys are values, values are labels or spec hashes; insertion order is display order)
     #
     # @example Basic usage
     #   choice = Clack.select(
@@ -60,7 +62,7 @@ module Clack
       def build_frame
         option_lines = visible_options.each_with_index.map do |opt, idx|
           actual_idx = @scroll_offset + idx
-          "#{bar}  #{option_display(opt, actual_idx == @option_index)}\n"
+          "#{gutter(active_bar)}#{option_display(opt, actual_idx == @option_index)}\n"
         end.join
 
         "#{frame_header}#{option_lines}#{frame_footer}"
@@ -70,6 +72,11 @@ module Clack
 
       private
 
+      # Upstream SELECT_INSTRUCTIONS
+      def keyboard_hints
+        [key_hint(Symbols::S_ARROWS_UP_DOWN, "to navigate"), key_hint("Enter:", "confirm")]
+      end
+
       def move_cursor(delta)
         super
         update_value

data/lib/clack/prompts/select_key.rb

@@ -5,11 +5,14 @@ module Clack
     # Quick selection via keyboard shortcuts.
     #
     # Each option has an associated key. Pressing that key immediately
-    # selects the option and submits.
+    # selects the option and submits (running +validate:+ and +transform:+
+    # like every other prompt).
     #
     # Options format:
     # - `{ value: "x", label: "Do X", key: "x" }` - explicit key
     # - `{ value: "create", label: "Create" }` - key defaults to first char
+    # - `{ create: "Create", quit: "Quit" }` - Hash shorthand (value => label, key defaults to first char)
+    # - `{ create: { label: "New project", key: "n" } }` - Hash shorthand with explicit key
     #
     # @example Basic usage
     #   action = Clack.select_key(
@@ -23,65 +26,85 @@ module Clack
     #
     class SelectKey < Core::Prompt
       # @param message [String] the prompt message
-      # @param options [Array<Hash>] options with :value, :label, and optionally :key, :hint
+      # @param options [Array<Hash>, Hash] options with :value, :label, and optionally :key, :hint,
+      #   or a Hash of value => label (or value => {label:, key:, hint:})
+      # @param case_sensitive [Boolean] match keys exactly instead of case-insensitively (default: false)
+      # @param initial_value [Object, nil] value of the option highlighted at start; Enter submits it.
+      #   The highlight is a color effect, so when colors are off mark the default in that option's +hint:+.
+      #   A value that matches no option is ignored with a warning on stderr.
       # @param opts [Hash] additional options passed to {Core::Prompt}
-      def initialize(message:, options:, **opts)
+      def initialize(message:, options:, case_sensitive: false, initial_value: nil, **opts)
         super(message:, **opts)
         @options = normalize_options(options)
+        @case_sensitive = case_sensitive
+        @option_index = find_initial_index(initial_value)
+        @value = current_option&.value
       end
 
       protected
 
+      # Option keys take precedence over every action except :cancel, so a
+      # custom alias such as `"y" => :enter` cannot hide a `y` option.
       def handle_key(key)
         return if terminal_state?
 
-        action = Core::Settings.action?(key)
+        idx = @options.find_index { |opt| key_match?(opt.key, key) }
+        return super if idx.nil? || Core::Settings.action?(key) == :cancel
 
-        case action
-        when :cancel
-          @state = :cancel
-        else
-          opt = @options.find { |o| o.key&.downcase == key&.downcase }
-          return unless opt
-
-          @value = opt.value
-          @state = :submit
-        end
+        @option_index = idx
+        @value = current_option.value
+        submit
       end
 
-      def build_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-        lines << help_line
+      def can_submit? = !@option_index.nil?
 
-        @options.each do |opt|
-          lines << "#{bar}  #{option_display(opt)}\n"
-        end
+      def build_frame
+        option_lines = @options.each_with_index.map do |opt, idx|
+          "#{gutter(active_bar)}#{option_display(opt, active_row?(idx))}\n"
+        end.join
 
-        lines << "#{Colors.gray(Symbols::S_BAR_END)}\n"
-        lines.join
+        "#{frame_header}#{option_lines}#{frame_footer}"
       end
 
-      def final_display = @options.find { |o| o.value == @value }&.label.to_s
+      def final_display = current_option ? current_option.label.to_s : ""
 
       private
 
+      def current_option = @option_index && @options[@option_index]
+
       def normalize_options(options)
-        options.map do |opt|
+        Core::OptionsHelper.option_entries(options).map do |opt|
           Clack::Core::SelectKeyOption.new(
             value: opt[:value],
             label: opt[:label] || opt[:value].to_s,
-            key: opt[:key] || opt[:value].to_s[0],
+            key: (opt[:key] || opt[:value].to_s[0])&.to_s,
             hint: opt[:hint]
           )
         end
       end
 
-      def option_display(opt)
-        key_display = Colors.cyan("[#{opt.key}]")
+      def find_initial_index(initial_value)
+        return nil if initial_value.nil?
+
+        idx = @options.find_index { |opt| opt.value == initial_value }
+        warn "[clack] ignoring unknown initial_value: #{initial_value.inspect}" unless idx
+        idx
+      end
+
+      def key_match?(option_key, key)
+        return false if option_key.nil? || key.nil?
+
+        @case_sensitive ? option_key == key : option_key.downcase == key.downcase
+      end
+
+      # The highlighted row: only meaningful while the prompt is still open.
+      def active_row?(idx) = idx == @option_index && !terminal_state?
+
+      def option_display(opt, active)
+        badge = Colors.cyan("[#{opt.key}]")
+        badge = Colors.inverse(badge) if active
         hint = opt.hint ? " #{Colors.dim("(#{opt.hint})")}" : ""
-        "#{key_display} #{opt.label}#{hint}"
+        "#{badge} #{opt.label}#{hint}"
       end
     end
   end