inquirex-tty 0.10.0 → 0.12.1

data/lib/inquirex/tty/key_map.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    # Raised out of a tty-prompt widget when the user presses a navigation
+    # key, so whichever widget is open (ask, select, multi_select, yes?)
+    # unwinds without returning an answer. tty-prompt offers no hook that
+    # aborts a question, and a subclass per widget would mean overriding the
+    # read loop of each one; one exception covers them all.
+    class Navigation < StandardError
+      # @return [Symbol] :back, :skip or :help
+      attr_reader :action
+
+      # @param action [Symbol] :back, :skip or :help
+      def initialize(action)
+        @action = action
+        super("navigation: #{action}")
+      end
+    end
+
+    # The keys that navigate a TTY run, as a tty-reader listener that turns
+    # them into {Navigation} exceptions while a collecting prompt is open.
+    #
+    # Backspace and "?" are also editing keys, so in a text answer they
+    # navigate only while the answer is empty: Backspace on an empty line
+    # goes back, Backspace after text deletes a character, and "what?" types
+    # a question mark. Lists have no text, so there they always navigate.
+    # Ctrl-B goes back from anywhere: tty-reader maps byte 0x02 to :ctrl_b in
+    # every terminal and tty-prompt binds nothing to it.
+    #
+    # tty-reader reports a key after it has edited the line, so the listener
+    # cannot ask "was the line empty?" directly. It keeps its own count of the
+    # characters typed instead, from how much each event's line grew or
+    # shrank. A pre-filled answer is a tty-prompt +default:+, shown beside
+    # the question rather than typed into the line, so every line starts empty.
+    #
+    # @example Wrap a prompt call
+    #   prompt.subscribe(KeyMap.new(can_back: engine.can_back?))
+    class KeyMap
+      # tty-reader key names that edit text and go back on an empty answer.
+      BACKSPACE = %i[backspace ctrl_h].freeze
+
+      # Every navigation key, for the help box.
+      BINDINGS = [
+        ["Enter",      "submit the answer (an empty answer keeps the one shown)"],
+        ["Backspace",  "go back to the previous question (on an empty answer)"],
+        ["Ctrl-B",     "go back to the previous question"],
+        ["Ctrl-S",     "skip the question (optional questions only)"],
+        ["↑ ↓  Space", "move and toggle in a list"],
+        ["?",          "show this help (on an empty answer)"],
+        ["Ctrl-C",     "abort without saving"]
+      ].freeze
+
+      # @param can_back [Boolean] whether there is a question to go back to;
+      #   when false the back keys do nothing
+      def initialize(can_back: true)
+        @can_back = can_back
+        @length   = 0
+        @line     = nil
+      end
+
+      # The one-line reminder drawn above each collecting prompt.
+      #
+      # @param can_back [Boolean]
+      # @return [String]
+      def self.hint(can_back:)
+        [("⌫ back" if can_back), "^S skip", "? keys", "^C abort"].compact.join(" · ")
+      end
+
+      # tty-reader calls this for every key, after any key-specific handler.
+      #
+      # @param event [TTY::Reader::KeyEvent]
+      # @return [void]
+      # @raise [Navigation] when the key navigates
+      def keypress(event)
+        name = event.key.name
+        raise Navigation, :skip if name == :ctrl_s
+        raise Navigation, :back if @can_back && (name == :ctrl_b || (BACKSPACE.include?(name) && @length.zero?))
+        raise Navigation, :help if event.value == "?" && @length.zero?
+
+        track(event)
+      end
+
+      private
+
+      # Updates the typed-character count after an editing key.
+      #
+      # A line widget passes its whole line (prompt plus text) with each
+      # event; list widgets pass an empty string, and the only text they hold
+      # is the number typed into an enum_select.
+      #
+      # @param event [TTY::Reader::KeyEvent]
+      # @return [void]
+      def track(event)
+        return reset if %i[return enter].include?(event.key.name)
+        return track_keys(event) if event.line.to_s.empty?
+
+        delta = @line ? event.line.length - @line.length : first_delta(event)
+        @length = [@length + delta, 0].max
+        @line = event.line
+      end
+
+      # The first event of a line has nothing to diff against; the line
+      # started empty, so only a printable character changed it.
+      def first_delta(event) = printable?(event.value) ? 1 : 0
+
+      def track_keys(event)
+        if BACKSPACE.include?(event.key.name) || event.key.name == :delete
+          @length = [@length - 1, 0].max
+        elsif event.key.name == :num
+          @length += event.value.length
+        end
+      end
+
+      # Enter submits; a widget that reads several lines (multiline text)
+      # starts the next one empty.
+      def reset
+        @length = 0
+        @line = nil
+      end
+
+      def printable?(value)
+        value.to_s.length == 1 && value.match?(/[[:print:]]/)
+      end
+    end
+  end
+end

data/lib/inquirex/tty/renderer.rb

@@ -23,6 +23,11 @@ module Inquirex
     #   (fallback)     → prompt.ask
     #
     # Header display verb uses TTY::Font for large ASCII-art section titles.
+    #
+    # {#collect} drives one collecting step against an engine and binds the
+    # navigation keys ({KeyMap}): back steps the engine back and the caller's
+    # loop re-asks the previous question with its answer as the default; skip
+    # declines an optional question; "?" shows the keymap.
     class Renderer
       include UIHelper
 
@@ -62,6 +67,52 @@ module Inquirex
         sep(:magenta, "─")
       end
 
+      # Asks the engine's current collecting step and answers it, unless the
+      # user presses a navigation key ({KeyMap}) instead:
+      #
+      # - back: the engine steps back and nothing is answered; the caller's
+      #   loop then asks the previous question again, pre-filled with the
+      #   answer it had. Back is offered only when there is somewhere to go
+      #   back to: on the first question the keys do nothing.
+      # - skip: an optional question is skipped (Engine#skip); a required one
+      #   is refused with a notice and asked again.
+      # - help: the keymap is shown, then the loop asks the question again.
+      #
+      # @example Drive a flow's collecting steps
+      #   until engine.finished?
+      #     engine.current_step.display? ? (renderer.render(engine.current_step); engine.advance) : renderer.collect(engine)
+      #   end
+      #
+      # @param engine [Inquirex::Engine] positioned on a collecting step
+      # @return [Symbol] +:answered+, +:back+, +:skipped+, +:help+, or +:stay+
+      #   when a required question refused a skip
+      def collect(engine)
+        step_id  = engine.current_step_id
+        can_back = engine.can_back?
+        puts pastel.dim(KeyMap.hint(can_back:))
+
+        answer = with_keys(can_back) do
+          render(engine.current_step,
+            suggestion: engine.suggestion_for(step_id),
+            default:    engine.previous_answer(step_id))
+        end
+        engine.answer(answer)
+        :answered
+      rescue Navigation => e
+        navigate(engine, e.action)
+      end
+
+      # Shows every navigation key in a box and waits for a key.
+      #
+      # @return [void]
+      def show_keymap
+        width = KeyMap::BINDINGS.map { |key, _| key.length }.max
+        lines = KeyMap::BINDINGS.map { |key, action| "#{key.ljust(width)}   #{action}" }
+        puts
+        puts box(lines.join("\n"), title: "Keys", bg: :blue, fg: :white, align: :left)
+        prompt.keypress(pastel.dim("Press any key to return to the question..."))
+      end
+
       # Renders a node. Returns the collected answer, or +nil+ for display verbs.
       #
       # @example Collect an answer for the current step, pre-checking LLM suggestions
@@ -74,9 +125,12 @@ module Inquirex
       # @param suggestion [Array, nil] prefill suggestion for the step (option
       #   form values, e.g. from Engine#suggestion_for) — multi-select prompts
       #   render these choices pre-checked so the user confirms or extends
+      # @param default [Object, nil] the answer to pre-fill, e.g. the one the
+      #   user gave before going back (Engine#previous_answer)
       # @return [Object, nil]
-      def render(node, suggestion: nil)
+      def render(node, suggestion: nil, default: nil)
         @current_suggestion = suggestion
+        @current_default    = default
         if node.display?
           render_display_verb(node)
           nil
@@ -85,10 +139,124 @@ module Inquirex
         end
       ensure
         @current_suggestion = nil
+        @current_default    = nil
       end
 
       private
 
+      # Runs the block with the navigation keys live. The {KeyMap} listens
+      # only while the block runs, so a "Press any key" on a display step
+      # treats every key as any key.
+      #
+      # tty-prompt subscribes each question to the reader and unsubscribes it
+      # only when the question returns normally, and tty-reader's
+      # subscribe-with-a-block does the same. A question unwound by
+      # {Navigation} would stay subscribed and go on reacting to every later
+      # keypress, so every listener added while the block ran, the KeyMap
+      # included, is removed here.
+      #
+      # @param can_back [Boolean]
+      # @return [Object] the block's value
+      # @raise [Navigation] when a navigation key is pressed
+      def with_keys(can_back)
+        return yield unless prompt.respond_to?(:subscribe)
+
+        listeners = reader_registrations&.to_a
+        key_map = KeyMap.new(can_back:)
+        prompt.subscribe(key_map)
+        yield
+      ensure
+        if key_map
+          drop_listeners_since(listeners)
+          prompt.unsubscribe(key_map)
+        end
+      end
+
+      # Acts on a navigation key pressed during {#collect}.
+      #
+      # @param engine [Inquirex::Engine]
+      # @param action [Symbol] :back, :skip or :help
+      # @return [Symbol] what {#collect} returns
+      def navigate(engine, action)
+        case action
+        when :back then go_back(engine)
+        when :skip then skip(engine)
+        else
+          show_keymap
+          :help
+        end
+      end
+
+      # @param engine [Inquirex::Engine]
+      # @return [Symbol] :skipped, or :stay when the question is required
+      def skip(engine)
+        if engine.current_step.required?
+          puts pastel.yellow("  ⚠ This question is required and cannot be skipped.")
+          return :stay
+        end
+
+        puts pastel.dim("↷ skipped #{engine.current_step_id}")
+        engine.skip
+        :skipped
+      end
+
+      # @param before [Array, nil] the reader's registrations before the prompt opened
+      # @return [void]
+      def drop_listeners_since(before)
+        live = reader_registrations
+        return unless before && live
+
+        (live.to_a - before).each { |stale| live.delete(stale) }
+      end
+
+      # tty-reader keeps its listeners in Wisper's registration set, which it
+      # exposes only privately (its own #unsubscribe reads it the same way).
+      #
+      # @return [Set, nil]
+      def reader_registrations
+        reader = prompt.respond_to?(:reader) ? prompt.reader : nil
+        return nil unless reader.respond_to?(:local_registrations, true)
+
+        reader.send(:local_registrations)
+      end
+
+      # Steps the engine back to the previous question. An LLM step between
+      # them is stepped over too: it asks the user nothing, and landing on it
+      # would rerun the extraction and carry the user straight forward again.
+      #
+      # @param engine [Inquirex::Engine]
+      # @return [Symbol] :back
+      def go_back(engine)
+        engine.back
+        engine.back while llm_step?(engine.current_step) && engine.can_back?
+        puts pastel.dim("↩ back to #{engine.current_step_id}")
+        :back
+      end
+
+      # @param node [Inquirex::Node, nil]
+      # @return [Boolean]
+      def llm_step?(node) = node.respond_to?(:llm_verb?) && node.llm_verb?
+
+      # tty-prompt's `default:` option for the value being pre-filled.
+      #
+      # @param value [Object, nil] defaults to the value passed to #render
+      # @return [Hash] {} or { default: value }
+      def default_option(value = @current_default)
+        value.nil? ? {} : { default: value }
+      end
+
+      # select and enum_select preselect by choice NAME, the label the user
+      # sees, while answers are option values; translate back.
+      #
+      # @param node [Inquirex::Node]
+      # @return [Hash] {} or { default: label }
+      def choice_default(node)
+        return {} if @current_default.nil?
+
+        labels = node.respond_to?(:option_labels) ? node.option_labels : nil
+        { default: labels&.fetch(@current_default.to_s, nil) || @current_default.to_s }
+      end
+
       # Dispatches display verbs to their styled renderers.
       # :header uses TTY::Font for a large ASCII-art title.
       # :btw and :warning use TTY::Box info/warn boxes.
@@ -164,13 +332,14 @@ module Inquirex
 
       # Single-line text.
       def render_text_input(node)
-        prompt.ask(node.question)
+        prompt.ask(node.question, **default_option)
       end
 
       # Multi-line text (empty line to submit).
       def render_multiline(node)
         puts pastel.bold(node.question)
         puts pastel.dim("Enter your response. Press Enter on a blank line to submit.")
+        puts pastel.dim("Previous answer:\n#{@current_default}") unless @current_default.nil?
         sep(:cyan, "─")
         collect_multiline_text
       end
@@ -210,9 +379,9 @@ module Inquirex
       # @param convert [Symbol] :int or :float
       # @return [Numeric, nil]
       def ask_bounded(node, convert:)
-        return prompt.ask(node.question, convert:) unless node.bounded?
+        return prompt.ask(node.question, convert:, **default_option) unless node.bounded?
 
-        prompt.ask(node.question, convert:, in: bounds_range(node)) do |q|
+        prompt.ask(node.question, convert:, in: bounds_range(node), **default_option) do |q|
           q.messages[:range?] = "Enter a value #{describe_bounds(node)}."
         end
       end
@@ -239,16 +408,17 @@ module Inquirex
 
       # Boolean — tty-prompt yes?.
       def render_yes_no(node)
-        prompt.yes?(node.question)
+        prompt.yes?(node.question, **default_option)
       end
 
       # Single-choice scrollable menu.
       def render_select(node)
-        prompt.select(node.question, select_options(node))
+        prompt.select(node.question, select_options(node), **choice_default(node))
       end
 
       # Multiple-choice list (space to toggle, min 1 selection). Suggested
-      # choices (an LLM extraction the user should confirm) render pre-checked.
+      # choices (an LLM extraction the user should confirm) render pre-checked,
+      # and after going back, the choices the user had made.
       def render_multi_select(node)
         prompt.multi_select(node.question, select_options(node), min: 1, **multi_select_defaults(node))
       end
@@ -261,7 +431,7 @@ module Inquirex
       # @param node [Inquirex::Node]
       # @return [Hash] {} or { default: Array<String> }
       def multi_select_defaults(node)
-        suggested = Array(@current_suggestion)
+        suggested = Array(@current_default.nil? ? @current_suggestion : @current_default)
         return {} if suggested.empty?
 
         labels = node.respond_to?(:option_labels) ? node.option_labels : nil
@@ -271,7 +441,7 @@ module Inquirex
 
       # Numbered choice menu.
       def render_enum_select(node)
-        prompt.enum_select(node.question, select_options(node))
+        prompt.enum_select(node.question, select_options(node), **choice_default(node))
       end
 
       # Hidden / masked input.
@@ -288,7 +458,7 @@ module Inquirex
           opts[:max]  = hint_opts[:max]  if hint_opts[:max]
           opts[:step] = hint_opts[:step] if hint_opts[:step]
         end
-        prompt.slider(node.question, **opts)
+        prompt.slider(node.question, **opts, **default_option)
       end
 
       # Aliases: date, email, phone degrade to plain text_input in TTY.

data/lib/inquirex/tty/ui_helper.rb

@@ -39,13 +39,14 @@ module Inquirex
             # @param title [String, nil] optional title on the top border
             # @param bg [Symbol] background color name
             # @param fg [Symbol] foreground color name
+            # @param align [Symbol] :center, :left or :right
             # @return [void]
-            def box(text, title: nil, bg: :green, fg: :white) # rubocop:disable Naming/MethodParameterName
+            def box(text, title: nil, bg: :green, fg: :white, align: :center) # rubocop:disable Naming/MethodParameterName
               w = [width, 80].min
               args = {
                 width:   w,
                 padding: { top: 0, bottom: 0, left: 1, right: 1 },
-                align:   :center,
+                align:   align,
                 style:   { fg: fg, bg: bg,
                          border: { type: :thin, fg: fg, bg: bg } }
               }

data/lib/inquirex/tty/version.rb

@@ -2,6 +2,6 @@
 
 module Inquirex
   module TTY
-    VERSION = "0.10.0"
+    VERSION = "0.12.1"
   end
 end

data/lib/inquirex/tty.rb

@@ -40,6 +40,8 @@ require_relative "tty/version"
 require_relative "tty/ui_helper"
 require_relative "tty/flow_loader"
 require_relative "tty/output_path"
+require_relative "tty/answers_file"
+require_relative "tty/key_map"
 require_relative "tty/renderer"
 require_relative "tty/commands/run"
 require_relative "tty/commands/validate"