inquirex 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3422d46566a55c973dc712fb60918cde34029d3dc739e36bb1eb2c40110f1f25
-  data.tar.gz: eb6e54e12a407b21547ac97ca7153b93af516713c0dbcaa83a2323f909f8f816
+  metadata.gz: 67e5f1389368dbb7416aa60a83a7cf613997e72d728d4fb10bd8290741c83901
+  data.tar.gz: 105ed41192f4208d7a856e2c12edae0403343f19af45faeae7d557e5bd7048ef
 SHA512:
-  metadata.gz: 42b3c45e598ebadec67d48e251605e74022cfe1ba0923c21b5998b0c0c2ef8005f2895e43c501dfd9a8613d05821a95653330c5395ff7755fa1892a74761873c
-  data.tar.gz: c85a9f013fb304ddfc7cbb9742a24167c7da7cefe18fa83425cfc83f1ac5184eeb7960a9ee3592d95ebd82890f7b9568aaea2b1eb488d8840a17106cbe091f3f
+  metadata.gz: 9b2a1379ab0b37450c4621b03068939e63a1559dc5dec0d91de03d3819ba765d93f1c2587313738f5bd93bf0a9bbdfb8de5061f715d563407a49b306d7819d6d
+  data.tar.gz: 66313dc2a02d2ee469c8076e752ca73b5cd15b857ae475f91e566eea0f18f1756f8dfdddb87b9e66ce7fbde58a5871fc30fcd56bf30f9d812f3dc3abbfae4883

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-21
+
+- `required false` DSL builder method on collecting steps (`ask`, `confirm`): marks a question as optional so widgets render a small Skip control. Default remains `required true`, so every existing flow is unchanged.
+- `Node#required?` predicate; step JSON gains `"required": false` (omitted when true), round-tripping through `to_json` / `from_json`.
+- `Engine#skip` — user-initiated skip of the current optional step: records the step's `default` (when declared) into the answers and accumulators exactly as if answered, marks the step id in the new `Engine#skipped` list, and advances through transitions like `#answer`. Raises `Errors::RequiredStepError` (new) on a required step, `NonCollectingStepError` on a display step.
+- Skip without a default writes no answers entry (a missing key and `nil` branch identically in rules; the "declined" signal lives in `skipped`).
+- `Engine#skipped` / `Engine#skipped?(step_id)` distinguish default-by-skip values from user-provided answers; the list survives `to_state` / `from_state` (string→symbol normalized) and is merged into `Engine#answers_with_metadata` under `:skipped`.
+- Steps elided automatically by `skip_if` rules are NOT marked as skipped — auto-elision is flow logic, `#skip` is a user action (see docs/design/required-and-skip.md).
+
 ## [0.6.0] - 2026-07-19
 
 - Post-completion `action` DSL verb with an extensible effect registry

data/README.md

@@ -173,6 +173,7 @@ engine.finished? # => true
 - `text "..."` for display steps
 - `options [...]` or `options key: "Label"` for enum-style inputs
 - `default value` or `default { |answers| ... }`
+- `required false` (marks a question optional — renderers show a Skip control; see [Optional Questions and Skipping](#optional-questions-and-skipping))
 - `skip_if rule`
 - `transition to: :next_step, if_rule: rule, requires_server: false`
 - `compute { |answers| ... }` (accepted by the DSL as a server-side hook; currently omitted from runtime JSON)
@@ -432,6 +433,7 @@ Behavior:
 
 - Use `answer(value)` on collecting steps
 - Use `advance` on display steps
+- Use `skip` on optional (`required false`) collecting steps the user declines (see [Optional Questions and Skipping](#optional-questions-and-skipping))
 - Use `finished?` to detect completion
 - Use `total(:price)` / `totals` to read running totals
 - Use `to_state` / `.from_state` for persistence/resume (totals included)
@@ -462,6 +464,61 @@ Pass a custom adapter to the engine:
 engine = Inquirex::Engine.new(definition, validator: my_validator)
 ```
 
+## Optional Questions and Skipping
+
+Every collecting step is **required by default** — the flow will not advance without an answer. Declare `required false` to make a question optional: renderers (the JS widget, the TTY adapter, the qualified.at wizard) show a small **Skip** control next to the input, and a user who declines the question moves on via `Engine#skip`.
+
+```ruby
+ask :dependents do
+  type :integer
+  question "How many dependents?"
+  required false        # renders a Skip control
+  default 0             # what a skip records into the answers
+  transition to: :adult_path, if_rule: greater_than(:dependents, 0)
+  transition to: :done
+end
+```
+
+When the user skips:
+
+- **With a `default`** — the default is recorded into `answers[:dependents]` and contributes to [accumulators](#accumulators) exactly as if the user had submitted it. Transition rules evaluate against the default, so branching stays deterministic.
+- **Without a `default`** — no answers entry is written at all (not even `nil`). Rules read a missing key as `nil`, so branching behaves as if the question were unanswered.
+- Either way the step id lands in `engine.skipped`, which is how a defaulted-by-skip value is **distinguished from an answer the user actually provided**:
+
+```ruby
+engine.skip                     # user pressed Skip on :dependents
+engine.answers[:dependents]     # => 0 (the default)
+engine.skipped                  # => [:dependents]
+engine.skipped?(:dependents)    # => true
+```
+
+Guard rails:
+
+- `skip` on a **required** step raises `Errors::RequiredStepError`
+- `skip` on a **display** step raises `Errors::NonCollectingStepError` (use `advance`)
+- `skip` after the flow finished raises `Errors::AlreadyFinishedError`
+
+The `skipped` list survives `to_state` / `.from_state` round-trips (string keys from JSON are normalized back to symbols), and `engine.answers_with_metadata` merges it into the answers under `:skipped` — so post-completion actions (webhook payloads, email templates) and API consumers see which values were defaults-by-skip.
+
+On the wire, step JSON carries `"required": false` (omitted when true, like other defaults):
+
+```json
+{
+  "dependents": {
+    "verb": "ask",
+    "type": "integer",
+    "question": "How many dependents?",
+    "default": 0,
+    "required": false,
+    "transitions": [{ "to": "done" }]
+  }
+}
+```
+
+> [!NOTE]
+>
+> **`skip_if` is not the same thing.** A `skip_if` rule is *flow logic*: the definition elides the step from the path automatically, no default kicks in, and the step is **not** added to `engine.skipped` — it was never presented, so the user cannot have declined it. `Engine#skip` is a *user action* on a question that was presented. See [`docs/design/required-and-skip.md`](docs/design/required-and-skip.md) for the full design.
+
 ## Completion Metadata
 
 When a flow finishes, the engine guarantees a `CompletionMetadata` — an OpenStruct describing how the answers were collected. Only `engine` and `engine_version` are required members; rendering front-ends attach richer environment details from an `after_completion` hook:
@@ -571,6 +628,7 @@ Important serialization details:
 - Rule objects and accumulator shapes serialize and deserialize cleanly
 - Proc/lambda defaults are stripped from JSON
 - `requires_server: true` transition flag is preserved
+- `required: false` step flag is preserved (omitted when true, the default)
 - Snake-case theme keys are converted to camelCase on serialization to match the JS widget contract
 
 ## Answers Wrapper
@@ -615,6 +673,7 @@ Common exceptions under `Inquirex::Errors`:
 - `AlreadyFinishedError`
 - `ValidationError`
 - `NonCollectingStepError`
+- `RequiredStepError`
 
 ## Development
 

data/lib/inquirex/dsl/step_builder.rb

@@ -17,6 +17,7 @@ module Inquirex
         @transitions = []
         @skip_if = nil
         @default = nil
+        @required = true
         @compute = nil
         @widget_hints = {}
         @accumulations = []
@@ -114,12 +115,33 @@ module Inquirex
 
       # Sets a default value for this step (shown pre-filled; user can change it).
       # Can be a static value or a proc receiving collected answers so far.
+      # On a `required false` step the default is also what Engine#skip records
+      # into the answers when the user skips the question.
       #
       # @param value [Object, Proc]
       def default(value = nil, &block)
         @default = block || value
       end
 
+      # Declares whether the user must answer this step (true by default).
+      # `required false` marks the question as optional: renderers show a small
+      # Skip control, and Engine#skip records the step's default (when one is
+      # declared) into the answers while marking the step as skipped.
+      #
+      # @example An optional question with a skip default
+      #   ask :dependents do
+      #     type :integer
+      #     question "How many dependents?"
+      #     required false
+      #     default 0
+      #     transition to: :done
+      #   end
+      #
+      # @param value [Boolean] false to make the step skippable
+      def required(value = true)
+        @required = value
+      end
+
       # Registers a compute block: auto-calculates a value from answers, not shown to user.
       # The computed value is stored server-side only and stripped from JSON serialization.
       #
@@ -143,6 +165,7 @@ module Inquirex
           transitions:   @transitions,
           skip_if:       @skip_if,
           default:       @default,
+          required:      @required,
           widget_hints:  resolve_widget_hints,
           accumulations: @accumulations
         )

data/lib/inquirex/engine/state_serializer.rb

@@ -12,6 +12,7 @@ module Inquirex
         answers:             ->(v) { symbolize_answers(v) },
         totals:              ->(v) { symbolize_answers(v) },
         suggestions:         ->(v) { symbolize_answers(v) },
+        skipped:             ->(v) { Array(v).map { |e| e&.to_sym } },
         completion_metadata: ->(v) { symbolize_answers(v) }
       }.freeze
 

data/lib/inquirex/engine.rb

@@ -6,6 +6,7 @@ module Inquirex
   #
   # Collecting steps (ask, confirm): call engine.answer(value)
   # Display steps (say, header, btw, warning): call engine.advance
+  # Optional steps (declared `required false`): engine.skip is also allowed
   #
   # Validates each answer via an optional Validation::Adapter, then advances using
   # node transitions. Skips steps whose skip_if rule evaluates to true.
@@ -30,6 +31,15 @@ module Inquirex
     # @return [Hash{Symbol => Array}]
     attr_reader :suggestions
 
+    # Step ids the user explicitly skipped via #skip, in the order they were
+    # skipped. Distinguishes default-by-skip values in answers from values the
+    # user actually provided. Steps elided automatically by their skip_if rule
+    # are NOT listed here — they were never presented, so the user cannot have
+    # declined them.
+    #
+    # @return [Array<Symbol>]
+    attr_reader :skipped
+
     # Exceptions raised by after_completion hooks, in the order they were
     # raised. Hooks are isolated from one another, so a raising hook is
     # recorded here rather than propagated — callers that care can inspect
@@ -51,6 +61,7 @@ module Inquirex
       @after_completion_hooks = []
       @completion_hook_errors = []
       @suggestions = {}
+      @skipped = []
       @history << @current_step_id
       skip_display_steps_if_needed
     end
@@ -105,6 +116,53 @@ module Inquirex
       advance_step
     end
 
+    # Skips the current optional collecting step at the user's request — the
+    # engine-side handler for a widget's Skip button. Only steps declared with
+    # `required false` may be skipped.
+    #
+    # When the step has a default, the default is recorded into the answers and
+    # contributes to accumulators exactly as if the user had submitted it; the
+    # step id lands in #skipped so consumers can tell the value apart from one
+    # the user actually provided. Without a default, no answers entry is
+    # written (rules read a missing key as nil, so branching is unaffected).
+    # Advances through transitions exactly like #answer.
+    #
+    # @example Optional question, skipped by the user
+    #   engine.current_step.required?  # => false
+    #   engine.skip
+    #   engine.answers[:dependents]    # => 0 (the step's default)
+    #   engine.skipped                 # => [:dependents]
+    #
+    # @return [void]
+    # @raise [Errors::AlreadyFinishedError] if the flow has already finished
+    # @raise [Errors::NonCollectingStepError] if the current step is a display verb
+    # @raise [Errors::RequiredStepError] if the current step is required
+    def skip
+      raise Errors::AlreadyFinishedError, "Flow is already finished" if finished?
+      raise Errors::NonCollectingStepError, "Step #{@current_step_id} is a display step; use #advance instead" \
+        unless current_step.collecting?
+      raise Errors::RequiredStepError, "Step #{@current_step_id} is required and cannot be skipped" \
+        if current_step.required?
+
+      node = current_step
+      default = resolve_default(node)
+      unless default.nil?
+        @answers[@current_step_id] = default
+        apply_accumulations(node, default)
+      end
+      @skipped << @current_step_id unless @skipped.include?(@current_step_id)
+      @suggestions.delete(@current_step_id)
+      advance_step
+    end
+
+    # Whether the user explicitly skipped the given step via #skip.
+    #
+    # @param step_id [Symbol, String] step id
+    # @return [Boolean]
+    def skipped?(step_id)
+      @skipped.include?(step_id.to_sym)
+    end
+
     # Merges a hash of { step_id => value } into the top-level answers without
     # clobbering answers the user has already provided. Used by LLM clarify
     # steps to populate downstream answers from free-text extraction so that
@@ -191,18 +249,23 @@ module Inquirex
         history:             @history,
         totals:              @totals,
         suggestions:         @suggestions,
+        skipped:             @skipped,
         completion_metadata: @completion_metadata&.to_h
       }
     end
 
     # The collected answers with the completion metadata (when a renderer
-    # attached one) merged in under the :completion_metadata key.
+    # attached one) merged in under the :completion_metadata key, and the
+    # user-skipped step ids (when any) under the :skipped key — so
+    # post-completion actions and API consumers can tell default-by-skip
+    # values apart from answers the user actually provided.
     #
     # @return [Hash]
     def answers_with_metadata
-      return @answers if @completion_metadata.nil?
-
-      @answers.merge(completion_metadata: @completion_metadata.to_h)
+      extra = {}
+      extra[:completion_metadata] = @completion_metadata.to_h if @completion_metadata
+      extra[:skipped] = @skipped.dup unless @skipped.empty?
+      extra.empty? ? @answers : @answers.merge(extra)
     end
 
     # Rebuilds an Engine from a previously saved state.
@@ -231,6 +294,7 @@ module Inquirex
       @after_completion_hooks = []
       @completion_hook_errors = []
       @suggestions = state[:suggestions] || {}
+      @skipped = state[:skipped] || []
     end
 
     # Whether +step_id+ names a multi-select step in the definition. Unknown
@@ -255,6 +319,19 @@ module Inquirex
       end
     end
 
+    # The step's default as a concrete value: a Proc default (server-side only,
+    # stripped from JSON) is called with the answers collected so far, exactly
+    # as a renderer pre-filling the field would resolve it.
+    #
+    # @param node [Node]
+    # @return [Object, nil]
+    def resolve_default(node)
+      default = node.default
+      return default unless default.is_a?(Proc)
+
+      default.arity.zero? ? default.call : default.call(@answers)
+    end
+
     def advance_step
       node = @definition.step(@current_step_id)
       next_id = node.next_step_id(@answers)

data/lib/inquirex/errors.rb

@@ -25,6 +25,10 @@ module Inquirex
     # Use Engine#advance for non-collecting steps.
     class NonCollectingStepError < EngineError; end
 
+    # Raised when Engine#skip is called on a step that is required (the default).
+    # Only steps declared with `required false` may be skipped by the user.
+    class RequiredStepError < EngineError; end
+
     # Raised when serializing or deserializing a Definition to/from JSON fails.
     class SerializationError < Error; end
 

data/lib/inquirex/node.rb

@@ -23,6 +23,8 @@ module Inquirex
   # @attr_reader transitions [Array<Transition>] ordered conditional next-step edges
   # @attr_reader skip_if [Rules::Base, nil] rule to skip this step entirely
   # @attr_reader default [Object, nil] default value (pre-fill, user can change)
+  # @attr_reader required [Boolean] whether the user must answer (true by default);
+  #   `required false` steps render a Skip control and accept Engine#skip
   # @attr_reader widget_hints [Hash{Symbol => WidgetHint}, nil] rendering hints per target
   class Node
     # Valid DSL verbs and which ones collect input from the user.
@@ -48,6 +50,7 @@ module Inquirex
       :transitions,
       :skip_if,
       :default,
+      :required,
       :widget_hints,
       :accumulations
 
@@ -60,6 +63,7 @@ module Inquirex
       transitions: [],
       skip_if: nil,
       default: nil,
+      required: true,
       widget_hints: nil,
       accumulations: [])
       @id = id.to_sym
@@ -70,6 +74,7 @@ module Inquirex
       @transitions = transitions.freeze
       @skip_if = skip_if
       @default = default
+      @required = required ? true : false
       @widget_hints = widget_hints&.freeze
       @accumulations = accumulations.freeze
       extract_options(options)
@@ -86,6 +91,15 @@ module Inquirex
       DISPLAY_VERBS.include?(@verb)
     end
 
+    # Whether the user must answer this step. True by default; steps declared
+    # with `required false` render a Skip control and accept Engine#skip.
+    # Only meaningful for collecting steps.
+    #
+    # @return [Boolean]
+    def required?
+      @required
+    end
+
     # Returns the explicit widget hint for the given target, or nil.
     #
     # @param target [Symbol] e.g. :desktop, :mobile, :tty
@@ -135,6 +149,7 @@ module Inquirex
         hash["options"] = serialize_options if @options
         hash["skip_if"] = @skip_if.to_h if @skip_if
         hash["default"] = @default unless @default.nil? || @default.is_a?(Proc)
+        hash["required"] = false unless @required
       elsif @text
         hash["text"] = @text
       end
@@ -169,6 +184,8 @@ module Inquirex
       transitions_data = hash["transitions"] || hash[:transitions] || []
       skip_if_data = hash["skip_if"] || hash[:skip_if]
       default = hash["default"] || hash[:default]
+      # Fetch chain (not ||) so an explicit false survives; absent key means required.
+      required = hash.fetch("required") { hash.fetch(:required, true) }
       widget_data = hash["widget"] || hash[:widget]
       accumulate_data = hash["accumulate"] || hash[:accumulate]
 
@@ -188,6 +205,7 @@ module Inquirex
         transitions:,
         skip_if:,
         default:,
+        required:,
         widget_hints:,
         accumulations:
       )

data/lib/inquirex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Inquirex
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul