inquirex 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f99f7adba97c905c55490b57467fe062251719bbb98d698fe49e6dd04360fcf7
-  data.tar.gz: 2c6850590153b96ee376ddaa0314c2de3cf729f6ea2d7c8f3d0ccb20d2359683
+  metadata.gz: 67e5f1389368dbb7416aa60a83a7cf613997e72d728d4fb10bd8290741c83901
+  data.tar.gz: 105ed41192f4208d7a856e2c12edae0403343f19af45faeae7d557e5bd7048ef
 SHA512:
-  metadata.gz: 18b95d28461f971551997bb177c6ead5c4165562f1d627460d58656440a0884bf0972eef2d97a31e3883f34720349be82e24e2fa567b7181eea0f14361182355
-  data.tar.gz: ed93da41fe8d2f66098b0165224e472d794d6f7ab9313dd8ec9a8a80b0d299ef5623d957361d83a27680b1ce3c025dd294fc6690c855c02a32df90348726718c
+  metadata.gz: 9b2a1379ab0b37450c4621b03068939e63a1559dc5dec0d91de03d3819ba765d93f1c2587313738f5bd93bf0a9bbdfb8de5061f715d563407a49b306d7819d6d
+  data.tar.gz: 66313dc2a02d2ee469c8076e752ca73b5cd15b857ae475f91e566eea0f18f1756f8dfdddb87b9e66ce7fbde58a5871fc30fcd56bf30f9d812f3dc3abbfae4883

data/CHANGELOG.md

@@ -1,22 +1,23 @@
 ## [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
-- `send_email` effect: builds `Mail::Message` objects (multipart text/HTML)
-  from `{{field}}` templates into `Answers#outbox`; delivery is the host
-  application's responsibility. The `mail` gem is a soft dependency.
+- `send_email` effect: builds `Mail::Message` objects (multipart text/HTML) from `{{field}}` templates into `Answers#outbox`; delivery is the host application's responsibility. The `mail` gem is a soft dependency.
 - `run { |answers, outbox| ... }` escape-hatch effect (stripped from JSON)
-- `webhook` effect: POSTs the answers envelope to a static https URL whose
-  host must be covered by the new top-level `allowed_domains` declaration;
-  enforcement runs in `Definition#validate!`, so tampered JSON definitions
-  fail at rehydration
+- `webhook` effect: POSTs the answers envelope to a static https URL whose host must be covered by the new top-level `allowed_domains` declaration; enforcement runs in `Definition#validate!`, so tampered JSON definitions fail at rehydration
 - `Inquirex::Actions::Runner` and `Inquirex::Actions.run(definition, answers)`
 - Actions serialize to/from JSON with their rule gates
-- `CompletionMetadata` (OpenStruct; `engine` and `engine_version` required)
-  stamped by the engine at flow completion, enrichable by front-ends via the
-  new `Engine#after_completion` hook, persisted in engine state, and merged
-  into answers by `Engine#answers_with_metadata`
+- `CompletionMetadata` (OpenStruct; `engine` and `engine_version` required) stamped by the engine at flow completion, enrichable by front-ends via the new `Engine#after_completion` hook, persisted in engine state, and merged into answers by `Engine#answers_with_metadata`
 
 ## [0.1.0] - 2026-04-13
 

data/README.md

@@ -31,7 +31,7 @@ It provides a rich DSL for creating dynamic user intake forms, with complexity r
 >
 > For technically inclined, Inquirex turns user forms into a directed graph, where nodes are either questions or statements (or UI transitions), while edges are AST-based logical conditions that can be stacked and joined in arbitrarily complex ways, allowing you to move from one question to any other based on the previous answer. See the details below.
 
-***Don't want to deal with figuring it out? Head to [Qualified.At](https://qualified.at/onboarding) and walk through the demo onboarding form, that exists specifically to show you how quickly you can have the same conceptually on your site, tailored to YOUR users.***
+***Don't want to deal with figuring it out? Head to [Qualified.At](https://qualified.at) and walk through the demo onboarding form, that exists specifically to show you how quickly you can have the same conceptually on your site, tailored to YOUR users.***
 
 ## Summary
 
@@ -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,14 +433,11 @@ 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)
-- Use `prefill!(hash)` to merge externally-supplied answers into the state,
-  e.g. fields extracted by an LLM from a free-text answer (see
-  [inquirex-llm](#extension-gems)). Existing answers are preserved; `nil`
-  and empty values are ignored so they don't spuriously satisfy
-  `not_empty` rules. The engine auto-advances past any newly-skippable step.
+- Use `prefill!(hash)` to merge externally-supplied answers into the state, e.g. fields extracted by an LLM from a free-text answer (see [inquirex-llm](#extension-gems)). Existing answers are preserved; `nil` and empty values are ignored so they don't spuriously satisfy `not_empty` rules. The engine auto-advances past any newly-skippable step.
 
 ```ruby
 engine = Inquirex::Engine.new(definition)
@@ -466,12 +464,64 @@ 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:
+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:
 
 ```ruby
 engine.after_completion do |eng|
@@ -485,21 +535,11 @@ engine.after_completion do |eng|
 end
 ```
 
-If no hook supplies one, the engine stamps the minimal core version
-(`engine: "inquirex"`, `engine_version: Inquirex::VERSION`). The metadata
-persists through `Engine#to_state` / `Engine.from_state`, and
-`engine.answers_with_metadata` merges it into the answers hash under
-`:completion_metadata` — which also makes it available to post-completion
-actions: webhook payloads carry it, and email templates can interpolate
-`{{completion_metadata.engine}}`.
+If no hook supplies one, the engine stamps the minimal core version (`engine: "inquirex"`, `engine_version: Inquirex::VERSION`). The metadata persists through `Engine#to_state` / `Engine.from_state`, and `engine.answers_with_metadata` merges it into the answers hash under `:completion_metadata` — which also makes it available to post-completion actions: webhook payloads carry it, and email templates can interpolate `{{completion_metadata.engine}}`.
 
 ## Post-Completion Actions
 
-After all questions are answered, `action` declarations run server-side with
-the collected answers. The flagship effect is `send_email`, which **builds**
-`Mail::Message` objects (the same object ActionMailer wraps) and attaches them
-to `answers.outbox` — **nothing is delivered**; the host application decides
-how and when to send.
+After all questions are answered, `action` declarations run server-side with the collected answers. The flagship effect is `send_email`, which **builds** `Mail::Message` objects (the same object ActionMailer wraps) and attaches them to `answers.outbox` — **nothing is delivered**; the host application decides how and when to send.
 
 ```ruby
 Inquirex.define id: "tax-intake-2025" do
@@ -554,31 +594,14 @@ end
 
 Key semantics:
 
-- **Templating is `{{field}}` interpolation only** — dot-notation keys resolved
-  against `Answers#to_flat_h`, deliberately inert (no code execution), so
-  definitions stored in a database render safely. Values interpolated into
-  `html:` bodies are HTML-escaped automatically; `text:` bodies stay verbatim.
-  The built-in `{{answers_summary}}` expands to all collected answers.
-- **`if:` gates** reuse the serializable rule AST (`not_empty(:email)`, ...).
-  A false rule records `:skipped` — declare no actions (or gate them) when a
-  flow should only save answers.
-- **`run { |answers, outbox| ... }`** is the full-Ruby escape hatch; like all
-  lambdas it is stripped from JSON.
-- **Failures are isolated**: a raising effect records `:failed` in
-  `outbox.results` and never blocks other actions.
+- **Templating is `{{field}}` interpolation only** — dot-notation keys resolved against `Answers#to_flat_h`, deliberately inert (no code execution), so definitions stored in a database render safely. Values interpolated into `html:` bodies are HTML-escaped automatically; `text:` bodies stay verbatim. The built-in `{{answers_summary}}` expands to all collected answers.
+- **`if:` gates** reuse the serializable rule AST (`not_empty(:email)`, ...). A false rule records `:skipped` — declare no actions (or gate them) when a flow should only save answers.
+- **`run { |answers, outbox| ... }`** is the full-Ruby escape hatch; like all lambdas it is stripped from JSON.
+- **Failures are isolated**: a raising effect records `:failed` in `outbox.results` and never blocks other actions.
 - **Images** in HTML bodies must be external URLs; attachments are unsupported.
-- The `mail` gem is a soft dependency, needed only when a message is built
-  (Rails hosts already have it via ActionMailer).
-- **`webhook url:`** POSTs `{"answers": {...}}` as JSON to a static URL. The
-  URL's host must be covered by `allowed_domains`, declared at the top of the
-  definition so the flow's egress surface is auditable at a glance. The check
-  runs inside `Definition.new` — a JSON definition whose webhook URL was
-  tampered with fails at *rehydration*, before anything executes. Also
-  enforced: https only (plain http just for localhost), no userinfo, no
-  `{{field}}` templates in URLs (the destination must be static), redirects
-  are not followed, and non-2xx responses record `:failed`.
-- Effects are extensible: `Inquirex::Actions.register(:save_record, MyEffect)`
-  gives a new verb both DSL and JSON wire support.
+- The `mail` gem is a soft dependency, needed only when a message is built (Rails hosts already have it via ActionMailer).
+- **`webhook url:`** POSTs `{"answers": {...}}` as JSON to a static URL. The URL's host must be covered by `allowed_domains`, declared at the top of the definition so the flow's egress surface is auditable at a glance. The check runs inside `Definition.new` — a JSON definition whose webhook URL was tampered with fails at *rehydration*, before anything executes. Also enforced: https only (plain http just for localhost), no userinfo, no `{{field}}` templates in URLs (the destination must be static), redirects are not followed, and non-2xx responses record `:failed`.
+- Effects are extensible: `Inquirex::Actions.register(:save_record, MyEffect)` gives a new verb both DSL and JSON wire support.
 
 ## Serialization
 
@@ -597,17 +620,15 @@ Serialized structure includes:
 - Steps and transitions
 - Rule AST payloads
 - Widget hints
-- Post-completion actions (`actions`) with their rules and effects; `run`
-  blocks are stripped, and an action left with no serializable effects is
-  omitted entirely
-- The `allowed_domains` egress allowlist, re-enforced against webhook URLs
-  every time a definition is rehydrated
+- Post-completion actions (`actions`) with their rules and effects; `run` blocks are stripped, and an action left with no serializable effects is omitted entirely
+- The `allowed_domains` egress allowlist, re-enforced against webhook URLs every time a definition is rehydrated
 
 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
@@ -652,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

@@ -11,6 +11,8 @@ module Inquirex
         history:             ->(v) { Array(v).map { |e| e&.to_sym } },
         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.
@@ -21,6 +22,24 @@ module Inquirex
     # @return [CompletionMetadata, nil] nil until the flow finishes
     attr_accessor :completion_metadata
 
+    # Answer suggestions produced by prefill! for multi-select steps, keyed by
+    # step id. A suggestion pre-populates the step's choices in a renderer but
+    # — unlike an answer — never satisfies skip_if rules: multi-select
+    # extraction is treated as a hint the user confirms and may extend, not a
+    # deterministic fact. Cleared per step once the user answers it.
+    #
+    # @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
@@ -41,6 +60,8 @@ module Inquirex
       @completion_metadata = nil
       @after_completion_hooks = []
       @completion_hook_errors = []
+      @suggestions = {}
+      @skipped = []
       @history << @current_step_id
       skip_display_steps_if_needed
     end
@@ -81,6 +102,7 @@ module Inquirex
       raise Errors::ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?
 
       @answers[@current_step_id] = value
+      @suggestions.delete(@current_step_id)
       apply_accumulations(current_step, value)
       advance_step
     end
@@ -94,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
@@ -115,12 +184,28 @@ module Inquirex
         next if value.respond_to?(:empty?) && value.empty?
 
         sym = key.to_sym
-        @answers[sym] = value unless @answers.key?(sym)
+        if multi_select_step?(sym)
+          # Multi-select extraction is a hint, not a fact: the user may have
+          # more selections in mind than the text revealed. Record it as a
+          # suggestion so renderers pre-check the choices while the question
+          # is still asked; skip_if rules see no answer and do not fire.
+          @suggestions[sym] = Array(value) unless @answers.key?(sym)
+        else
+          @answers[sym] = value unless @answers.key?(sym)
+        end
       end
       skip_if_needed unless finished?
       @answers
     end
 
+    # The prefill suggestion for a step, or nil when none was recorded.
+    #
+    # @param step_id [Symbol, String] step id
+    # @return [Array, nil] suggested selections for a multi-select step
+    def suggestion_for(step_id)
+      @suggestions[step_id.to_sym]
+    end
+
     # Registers a hook to run when the flow finishes. The block receives the
     # engine; front-ends typically use it to attach a rich
     # completion_metadata (host, user, ips, terminal, ...). Optional — after
@@ -163,18 +248,24 @@ module Inquirex
         answers:             @answers,
         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.
@@ -202,6 +293,17 @@ module Inquirex
       @completion_metadata = CompletionMetadata.from_h(state[:completion_metadata])
       @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
+    # ids (e.g. an extract schema field that matches no step) are not.
+    #
+    # @param step_id [Symbol]
+    # @return [Boolean]
+    def multi_select_step?(step_id)
+      @definition.step_ids.include?(step_id) && @definition.step(step_id).type == :multi_enum
     end
 
     def init_totals
@@ -217,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.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -36,23 +36,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".relaxed_rubocop.yml"
-- ".rub"
-- ".ruby-version"
-- ".secrets.baseline"
-- Brewfile
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- docs/badges/coverage_badge.svg
-- examples/01_readme_example.rb
-- examples/02_readme_mermaid.png
-- examples/02_readme_mermaid.rb
-- examples/03_send_email_actions.rb
-- examples/README.md
-- justfile
-- lefthook.yml
+- lib/.DS_Store
 - lib/inquirex.rb
 - lib/inquirex/accumulator.rb
 - lib/inquirex/actions.rb
@@ -92,7 +79,6 @@ files:
 - lib/inquirex/version.rb
 - lib/inquirex/widget_hint.rb
 - lib/inquirex/widget_registry.rb
-- sig/inquirex.rbs
 homepage: https://github.com/inquirex/inquirex
 licenses:
 - MIT