asktty 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4918843985d1b7a0204a197a2e8499ca7493e171bc4b16307407bab000572c15
-  data.tar.gz: af5db2494b82ba83bddd0813d40a86dd50833276ba6a00e8df3d2b9b79d1a5e4
+  metadata.gz: 7afce23120ce01740dd6c9f0e405080565efd3c22546361508611e8573a051aa
+  data.tar.gz: 8c2e75af399a24f63d9230112acbb07152d604f00da0d0cdc95098b9cf48fb31
 SHA512:
-  metadata.gz: 0fa70b12b633518b2ab3aac623dada69b67e337401c0d21d466126b0c6a24927921323941357ac81c259e16bc97c2eb75a9a03323af73aa4e0a17f10911bf300
-  data.tar.gz: 6fba726118b1e937822797c90b84cf840e69c70c77c1f0cc6a7ce772cc063e4ff242559157d031cae16592ddf1b150bafa5a3f35c8bf0d3348677591e6da4e94
+  metadata.gz: 2c164a8cd20c460cf1baa0739244155c2f24f862f6b987617245eeac91e1e55938b88d8c109d7ce87df1c05f1181c04e4e983c5ac2febdc8442ecb79364c5d84
+  data.tar.gz: 17f6e9e671a4ac84b1cb358f7648c03561b9212f06f4cafa7190f002e4c67f552b03f866236104da19cc772f365b3e147b63fdf03b3acc364a830d4136f275f1

data/README.md

@@ -1,18 +1,18 @@
 # AskTTY
 
-> Note: AskTTY is still under development and has not been released to RubyGems yet.
-
 A Ruby gem for interactive terminal prompts.
 
+<img src="https://raw.githubusercontent.com/vsuchy/asktty/refs/heads/main/assets/demo/demo.gif" alt="AskTTY Demo" width="600">
+
 ## Installation
 
-Install it globaly:
+Install it globally:
 
 ```sh
 gem install asktty
 ```
 
-or, add it to your application gemfile:
+or, add it to your application Gemfile:
 
 ```sh
 bundle add asktty
@@ -37,7 +37,7 @@ name = AskTTY::InputPrompt.ask(
 ### Text Prompt
 
 ```ruby
-notes = AskTTY::TextPrompt.ask(
+project = AskTTY::TextPrompt.ask(
   title: "Ruby Project",
   placeholder: "AskTTY\nTerminal prompts for Ruby"
 )
@@ -46,7 +46,7 @@ notes = AskTTY::TextPrompt.ask(
 ### Select Prompt
 
 ```ruby
-drink = AskTTY::SelectPrompt.ask(
+experience = AskTTY::SelectPrompt.ask(
   title: "Experience Level",
   options: [
     { label: "Beginner", value: :beginner },
@@ -57,10 +57,13 @@ drink = AskTTY::SelectPrompt.ask(
 )
 ```
 
+Select and multi-select options must be provided as a non-empty array of symbol-keyed `{ label:, value: }` hashes.
+Option values must be unique.
+
 ### MultiSelect Prompt
 
 ```ruby
-toppings = AskTTY::MultiSelectPrompt.ask(
+topics = AskTTY::MultiSelectPrompt.ask(
   title: "Topics",
   details: "Select all topics you are interested in.",
   options: [
@@ -86,7 +89,7 @@ confirmed = AskTTY::ConfirmPrompt.ask(
 
 ### Validation
 
-Pass a block that returns `true` when the current value is valid, or an error message when it is not:
+Pass a block that returns `true` when the current value is valid, or a non-empty error message when it is not:
 
 ```ruby
 name = AskTTY::InputPrompt.ask(title: "Name") do |value|

data/lib/asktty/internal/options.rb

@@ -3,32 +3,31 @@
 module AskTTY
   module Internal
     module Options
-      Option = Struct.new(:label, :value)
+      Option = Data.define(:label, :value)
+
+      private_constant :Option
 
       module_function
 
       def normalize(options)
-        raise AskTTY::Error, "options must not be empty" if options.nil? || options.empty?
+        raise AskTTY::Error, "options must be a non-empty array" unless options.is_a?(Array) && !options.empty?
 
-        options.map do |option|
-          next option if option.is_a?(Option)
+        values = []
 
+        options.map do |option|
           raise AskTTY::Error, "options must be hashes with label and value" unless option.is_a?(Hash)
 
-          label = option[:label] || option["label"]
-          has_value = option.key?(:value) || option.key?("value")
-          value = option[:value] if option.key?(:value)
-          value = option["value"] if option.key?("value")
+          unless option.key?(:label) && option.key?(:value) && !option[:label].nil?
+            raise AskTTY::Error, "options must include label and value"
+          end
 
-          raise AskTTY::Error, "options must include label and value" unless label && has_value
+          value = option[:value]
+          raise AskTTY::Error, "option values must be unique" if values.include?(value)
 
-          Option.new(label.to_s, value)
+          values << value
+          Option.new(option[:label].to_s, value)
         end
       end
-
-      def values(options)
-        options.map(&:value)
-      end
     end
   end
 end

data/lib/asktty/internal/rendering.rb

@@ -42,7 +42,7 @@ module AskTTY
         summary = value.to_s.empty? ? prefix : "#{prefix} #{value}"
         lines = wrap(summary, content_width(width))
 
-        frame(style_submitted_lines(lines, title_length: graphemes(prefix).length))
+        frame(lines.map { |line| ANSIStyle.text(line) })
       end
 
       def wrap(text, width)
@@ -53,6 +53,16 @@ module AskTTY
         split_lines(text.to_s).flat_map { |line| wrap_exact_line(line, width) }
       end
 
+      def prefixed_lines(text, prefix:, width:, style:)
+        prefix_width = display_width(prefix)
+        wrapped = wrap(text, [width - prefix_width, 1].max)
+
+        wrapped.each_with_index.map do |line, index|
+          current_prefix = index.zero? ? prefix : (" " * prefix_width)
+          current_prefix + style.call(line)
+        end
+      end
+
       def header_lines(title, details, width:)
         lines = wrap(title.to_s, width).map { |line| ANSIStyle.title(line) }
 
@@ -89,7 +99,8 @@ module AskTTY
           segment_width = display_width(segment)
 
           if width.to_i.positive? && total_width + segment_width > width
-            line << " …" if total_width + display_width(" …") <= width
+            ellipsis = line.empty? ? "…" : " …"
+            line << ellipsis if total_width + display_width(ellipsis) <= width
             break
           end
 
@@ -99,7 +110,13 @@ module AskTTY
 
         return "" if line.empty?
 
-        ANSIStyle.muted(line)
+        line.split(/(\([^)]*\))/).reject(&:empty?).map do |segment|
+          if segment.start_with?("(") && segment.end_with?(")")
+            ANSIStyle.muted(segment)
+          else
+            ANSIStyle.text(segment)
+          end
+        end.join
       end
 
       def content_width(width)
@@ -123,27 +140,6 @@ module AskTTY
         text.split("\n", -1)
       end
 
-      def style_submitted_lines(lines, title_length:)
-        remaining_title_length = title_length
-
-        lines.map do |line|
-          line_graphemes = graphemes(line)
-
-          if remaining_title_length >= line_graphemes.length
-            remaining_title_length -= line_graphemes.length
-            ANSIStyle.title(line)
-          elsif remaining_title_length.positive?
-            title_text = line_graphemes[0, remaining_title_length].join
-            value_text = line_graphemes[remaining_title_length..].to_a.join
-            remaining_title_length = 0
-
-            ANSIStyle.title(title_text) + ANSIStyle.text(value_text)
-          else
-            ANSIStyle.text(line)
-          end
-        end
-      end
-
       def wrap_line(line, width)
         return [""] if line.empty?
 
@@ -151,6 +147,11 @@ module AskTTY
         remaining = graphemes(line)
 
         until remaining.empty?
+          if lines.any?
+            remaining = remaining.drop_while { |grapheme| grapheme.match?(/\s/) }
+            break if remaining.empty?
+          end
+
           segment, last_whitespace_index = take_segment(remaining, width)
 
           if segment.length == remaining.length

data/lib/asktty/internal/terminal.rb

@@ -5,6 +5,11 @@ require "io/console"
 module AskTTY
   module Internal
     class Terminal
+      ESCAPE_START_TIMEOUT = 0.1
+      ESCAPE_CONTINUATION_TIMEOUT = 0.01
+
+      private_constant :ESCAPE_START_TIMEOUT, :ESCAPE_CONTINUATION_TIMEOUT
+
       attr_reader :width
 
       def self.open(&)
@@ -79,13 +84,16 @@ module AskTTY
 
       def read_escape_sequence
         sequence = +""
+        timeout = ESCAPE_START_TIMEOUT
 
-        while @input.wait_readable(0.01)
+        while @input.wait_readable(timeout)
           chunk = @input.read_nonblock(1, exception: false)
           break if chunk == :wait_readable || chunk.nil?
 
           sequence << chunk
           break if chunk.match?(/[A-Za-z~]/)
+
+          timeout = ESCAPE_CONTINUATION_TIMEOUT
         end
 
         sequence

data/lib/asktty/internal/text_input_prompt.rb

@@ -14,7 +14,8 @@ module AskTTY
 
       def ask
         value = @value.dup
-        validation_active = false
+        error_message = nil
+        validation_checked = false
 
         Terminal.open do |session|
           loop do
@@ -22,8 +23,7 @@ module AskTTY
               render(
                 value,
                 width: session.width,
-                show_cursor: true,
-                error_message: validation_message(value, validation_active)
+                error_message: error_message
               )
             )
 
@@ -31,8 +31,12 @@ module AskTTY
 
             case key
             when :enter
-              validation_active = true
-              next if validation_message(value, validation_active)
+              unless validation_checked
+                error_message = validation_message(value)
+                validation_checked = true
+              end
+
+              next if error_message
 
               session.render(submitted_render(value, width: session.width))
               return value
@@ -40,16 +44,21 @@ module AskTTY
               next unless @multiline
 
               value << "\n"
-              validation_active = true
+              error_message = validation_message(value)
+              validation_checked = true
             when :backspace
               updated_value = Rendering.chop_grapheme(value)
-              validation_active ||= updated_value != value
+              next if updated_value == value
+
               value = updated_value
+              error_message = validation_message(value)
+              validation_checked = true
             when String
               next unless printable?(key)
 
               value << key
-              validation_active = true
+              error_message = validation_message(value)
+              validation_checked = true
             end
           end
         end
@@ -57,11 +66,11 @@ module AskTTY
 
       private
 
-      def render(value, width:, show_cursor:, error_message: nil)
+      def render(value, width:, error_message: nil)
         Rendering.prompt_frame(
           title: @title, details: @details, help_items: help_items, error_message: error_message, width: width
         ) do |content_width|
-          body_lines(value, content_width: content_width, show_cursor: show_cursor)
+          body_lines(value, content_width: content_width)
         end
       end
 
@@ -69,15 +78,15 @@ module AskTTY
         Rendering.submitted_frame(@title, summary_value(value), width: width)
       end
 
-      def body_lines(value, content_width:, show_cursor:)
-        return placeholder_lines(content_width) if @placeholder && value.empty? && show_cursor
+      def body_lines(value, content_width:)
+        return placeholder_lines(content_width) if @placeholder && value.empty?
 
-        render_segments(value_lines(value), content_width: content_width, show_cursor: show_cursor)
+        render_segments(value_lines(value), content_width: content_width, show_cursor: true)
       end
 
       def placeholder_lines(content_width)
         render_segments(
-          @placeholder.to_s.split("\n", -1),
+          @placeholder.split("\n", -1),
           content_width: content_width,
           show_cursor: false,
           first_style: method(:placeholder_first_line),
@@ -114,7 +123,6 @@ module AskTTY
 
         segments.each_with_index.flat_map do |segment, segment_index|
           wrapped_segments = Rendering.wrap_exact(segment, wrap_width)
-          wrapped_segments = [""] if wrapped_segments.empty?
 
           if show_cursor && segment_index == last_index && Rendering.display_width(wrapped_segments.last) >= wrap_width
             wrapped_segments << ""
@@ -140,8 +148,8 @@ module AskTTY
         value.tr("\n", " ")
       end
 
-      def validation_message(value, validation_active)
-        Validation.message_for(value, @validator, active: validation_active)
+      def validation_message(value)
+        Validation.message_for(value, @validator)
       end
     end
   end

data/lib/asktty/internal/validation.rb

@@ -5,14 +5,14 @@ module AskTTY
     module Validation
       module_function
 
-      def message_for(value, validator, active:)
-        return nil unless active && validator
+      def message_for(value, validator)
+        return nil unless validator
 
         result = validator.call(value)
         return nil if result == true
-        return result if result.is_a?(String)
+        return result if result.is_a?(String) && !result.empty?
 
-        raise AskTTY::Error, "validator must return true or an error message"
+        raise AskTTY::Error, "validator must return true or a non-empty error message"
       end
     end
   end

data/lib/asktty/prompts/confirm_prompt.rb

@@ -6,6 +6,8 @@ module AskTTY
       new(title: title, details: details, value: value, validator: validator).ask
     end
 
+    private_class_method :new
+
     def initialize(title:, details: nil, value: false, validator: nil)
       @title = title.to_s
       @details = details&.to_s
@@ -17,27 +19,40 @@ module AskTTY
     end
 
     def ask
-      validation_active = false
+      error_message = nil
+      validation_checked = false
 
       Internal::Terminal.open do |session|
         loop do
-          session.render(render(width: session.width, error_message: validation_message(validation_active)))
+          session.render(render(width: session.width, error_message: error_message))
 
           case session.read_key
           when :enter
-            validation_active = true
-            next if validation_message(validation_active)
+            unless validation_checked
+              error_message = validation_message
+              validation_checked = true
+            end
+
+            next if error_message
 
             session.render(submitted_render(width: session.width))
             return @value
           when :left, "h"
             previous_value = @value
             @value = true
-            validation_active ||= @value != previous_value
+
+            if @value != previous_value
+              error_message = validation_message
+              validation_checked = true
+            end
           when :right, "l"
             previous_value = @value
             @value = false
-            validation_active ||= @value != previous_value
+
+            if @value != previous_value
+              error_message = validation_message
+              validation_checked = true
+            end
           end
         end
       end
@@ -84,8 +99,8 @@ module AskTTY
       ["enter (submit)", "left/right (select option)"]
     end
 
-    def validation_message(validation_active)
-      Internal::Validation.message_for(@value, @validator, active: validation_active)
+    def validation_message
+      Internal::Validation.message_for(@value, @validator)
     end
   end
 end

data/lib/asktty/prompts/input_prompt.rb

@@ -3,17 +3,16 @@
 module AskTTY
   class InputPrompt
     def self.ask(title:, details: nil, placeholder: nil, value: nil, &validator)
-      new(title: title, details: details, placeholder: placeholder, value: value, validator: validator).ask
+      Internal::TextInputPrompt.new(
+        title: title,
+        details: details,
+        placeholder: placeholder,
+        value: value,
+        validator: validator,
+        multiline: false
+      ).ask
     end
 
-    def initialize(title:, details: nil, placeholder: nil, value: nil, validator: nil)
-      @prompt = Internal::TextInputPrompt.new(
-        title: title, details: details, placeholder: placeholder, value: value, validator: validator, multiline: false
-      )
-    end
-
-    def ask
-      @prompt.ask
-    end
+    private_class_method :new
   end
 end

data/lib/asktty/prompts/multi_select_prompt.rb

@@ -6,32 +6,41 @@ module AskTTY
       new(title: title, details: details, options: options, values: values, validator: validator).ask
     end
 
+    private_class_method :new
+
     def initialize(title:, options:, details: nil, values: nil, validator: nil)
       @title = title.to_s
       @details = details&.to_s
       @options = Internal::Options.normalize(options)
-      @values = Array(values).uniq
       @validator = validator
 
-      option_values = Internal::Options.values(@options)
+      @values = Array(values).map do |value|
+        option = @options.find { |candidate| candidate.value == value }
+
+        raise AskTTY::Error, "values contain unknown option values" unless option
 
-      unknown_values = @values - option_values
-      raise AskTTY::Error, "values contain unknown option values" unless unknown_values.empty?
+        option.value
+      end
 
       @index = first_selected_index || 0
     end
 
     def ask
-      validation_active = false
+      error_message = nil
+      validation_checked = false
 
       Internal::Terminal.open do |session|
         loop do
-          session.render(render(width: session.width, error_message: validation_message(validation_active)))
+          session.render(render(width: session.width, error_message: error_message))
 
           case session.read_key
           when :enter
-            validation_active = true
-            next if validation_message(validation_active)
+            unless validation_checked
+              error_message = validation_message
+              validation_checked = true
+            end
+
+            next if error_message
 
             session.render(submitted_render(width: session.width))
             return selected_results
@@ -40,9 +49,9 @@ module AskTTY
           when :down, "j"
             move(1)
           when " "
-            previous_results = selected_results
             toggle_current
-            validation_active ||= selected_results != previous_results
+            error_message = validation_message
+            validation_checked = true
           end
         end
       end
@@ -68,10 +77,12 @@ module AskTTY
       @options.each_with_index.flat_map do |option, index|
         cursor = index == @index ? Internal::ANSIStyle.prompt("> ") : "  "
         selected = @values.include?(option.value)
-        prefix = selected ? Internal::ANSIStyle.selected("[•] ") : Internal::ANSIStyle.text("[ ] ")
+        marker = selected ? Internal::ANSIStyle.selected("[•] ") : Internal::ANSIStyle.text("[ ] ")
         style = selected ? Internal::ANSIStyle.method(:selected) : Internal::ANSIStyle.method(:text)
 
-        wrap_option(option.label, cursor: cursor, prefix: prefix, width: content_width, &style)
+        Internal::Rendering.prefixed_lines(
+          option.label, prefix: cursor + marker, width: content_width, style: style
+        )
       end
     end
 
@@ -105,18 +116,8 @@ module AskTTY
       end
     end
 
-    def validation_message(validation_active)
-      Internal::Validation.message_for(selected_results, @validator, active: validation_active)
-    end
-
-    def wrap_option(label, cursor:, prefix:, width:, &style)
-      prefix_width = Internal::Rendering.display_width(cursor + prefix)
-      wrapped = Internal::Rendering.wrap(label, [width - prefix_width, 1].max)
-
-      wrapped.each_with_index.map do |line, index|
-        current_prefix = index.zero? ? cursor + prefix : (" " * prefix_width)
-        current_prefix + style.call(line)
-      end
+    def validation_message
+      Internal::Validation.message_for(selected_results, @validator)
     end
   end
 end

data/lib/asktty/prompts/select_prompt.rb

@@ -2,12 +2,16 @@
 
 module AskTTY
   class SelectPrompt
-    UNSET = Object.new
+    UNSET = Object.new.freeze
+
+    private_constant :UNSET
 
     def self.ask(title:, options:, details: nil, value: UNSET, &validator)
       new(title: title, details: details, options: options, value: value, validator: validator).ask
     end
 
+    private_class_method :new
+
     def initialize(title:, options:, details: nil, value: UNSET, validator: nil)
       @title = title.to_s
       @details = details&.to_s
@@ -17,27 +21,40 @@ module AskTTY
     end
 
     def ask
-      validation_active = false
+      error_message = nil
+      validation_checked = false
 
       Internal::Terminal.open do |session|
         loop do
-          session.render(render(width: session.width, error_message: validation_message(validation_active)))
+          session.render(render(width: session.width, error_message: error_message))
 
           case session.read_key
           when :enter
-            validation_active = true
-            next if validation_message(validation_active)
+            unless validation_checked
+              error_message = validation_message
+              validation_checked = true
+            end
+
+            next if error_message
 
             session.render(submitted_render(width: session.width))
             return selected_option.value
           when :up, "k"
             previous_value = selected_option.value
             move(-1)
-            validation_active ||= selected_option.value != previous_value
+
+            if selected_option.value != previous_value
+              error_message = validation_message
+              validation_checked = true
+            end
           when :down, "j"
             previous_value = selected_option.value
             move(1)
-            validation_active ||= selected_option.value != previous_value
+
+            if selected_option.value != previous_value
+              error_message = validation_message
+              validation_checked = true
+            end
           end
         end
       end
@@ -62,7 +79,9 @@ module AskTTY
         prefix = index == @index ? Internal::ANSIStyle.prompt("> ") : "  "
         style = index == @index ? Internal::ANSIStyle.method(:selected) : Internal::ANSIStyle.method(:text)
 
-        wrap_option(option.label, prefix: prefix, width: content_width, &style)
+        Internal::Rendering.prefixed_lines(
+          option.label, prefix: prefix, width: content_width, style: style
+        )
       end
     end
 
@@ -85,17 +104,8 @@ module AskTTY
       @options[@index]
     end
 
-    def validation_message(validation_active)
-      Internal::Validation.message_for(selected_option.value, @validator, active: validation_active)
-    end
-
-    def wrap_option(label, prefix:, width:, &style)
-      wrapped = Internal::Rendering.wrap(label, [width - 2, 1].max)
-
-      wrapped.each_with_index.map do |line, index|
-        current_prefix = index.zero? ? prefix : "  "
-        current_prefix + style.call(line)
-      end
+    def validation_message
+      Internal::Validation.message_for(selected_option.value, @validator)
     end
   end
 end

data/lib/asktty/prompts/text_prompt.rb

@@ -3,17 +3,16 @@
 module AskTTY
   class TextPrompt
     def self.ask(title:, details: nil, placeholder: nil, value: nil, &validator)
-      new(title: title, details: details, placeholder: placeholder, value: value, validator: validator).ask
+      Internal::TextInputPrompt.new(
+        title: title,
+        details: details,
+        placeholder: placeholder,
+        value: value,
+        validator: validator,
+        multiline: true
+      ).ask
     end
 
-    def initialize(title:, details: nil, placeholder: nil, value: nil, validator: nil)
-      @prompt = Internal::TextInputPrompt.new(
-        title: title, details: details, placeholder: placeholder, value: value, validator: validator, multiline: true
-      )
-    end
-
-    def ask
-      @prompt.ask
-    end
+    private_class_method :new
   end
 end

data/lib/asktty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AskTTY
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/lib/asktty.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "asktty/version"
+
+module AskTTY
+  class Error < StandardError; end
+end
+
 require_relative "asktty/internal/ansi_style"
 require_relative "asktty/internal/options"
 require_relative "asktty/internal/rendering"
@@ -12,7 +17,3 @@ require_relative "asktty/prompts/text_prompt"
 require_relative "asktty/prompts/select_prompt"
 require_relative "asktty/prompts/multi_select_prompt"
 require_relative "asktty/prompts/confirm_prompt"
-
-module AskTTY
-  class Error < StandardError; end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asktty
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Vlad Suchy
@@ -65,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Terminal prompts for Ruby.
 test_files: []