easy_flow 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7f3a5cbb2c164df9c3c513c7de107dcb30123987e5392853e76554c242aff84
-  data.tar.gz: 320ffff05f4107aa8573b2be17a41b5a4e7aa49759b6228c74f7cd7905501b5a
+  metadata.gz: 7bb067f6cff8924c7e323248c1a6cc0d33113e725bb8ffa3c3f5450a667a19ca
+  data.tar.gz: 3d576a5fdc9bae4869117f0d22dec76d02041004e3de464c017162a44146102f
 SHA512:
-  metadata.gz: 40887692880f1f9f468d11818cac2912b2debb61bdce99a2e238d9be4338c4c915e61df7db046938f371c97eaf2e296ee2c8985a1a930960ef9ffc4bd45a25cb
-  data.tar.gz: e01daf58e09f740dd57a5e3690028755abd7c5b77f604bdf765c60637f0fb8974852eab79ed6ebc200225cca7ac4471fde33a75420ad7e00f87cd4ab786ac7f4
+  metadata.gz: ae53ac2b11a6bc22f14af4ed0f9b8ea2ce232d9cdfcf1ee034d587f890defed1ca83d3d18692fa97f33d1fd0ca9bd1ce1034c53941d62a60b64a77cc510e5993
+  data.tar.gz: 34f1b7ff9030aabece3d0a2dfa5a2b07ab1428049b6544de627d5e03136a33811b88774b8c8a15b03e9c164f8726dc0edb273f8787bae1b8b62a907d01295d28

data/app/controllers/easy_flow/flows_controller.rb

@@ -14,12 +14,15 @@ module EasyFlow
       @guide = runner_for(running_definition)
       @progress = progress
       @guide.run(@progress)
+      return redirect_to run_location(run.waiting_on) if run&.waiting_on
+
       @answers = @progress.recorded
       @question = @guide.next_step(@answers, run: run, times: @progress.completed_at)
       @drawing = @guide.drawing_at(@answers, times: @progress.completed_at)
       flash.now[:alert] = @refused if @refused
       @waiting = waiting_on(@question)
       return render :step if @question
+      return redirect_to run_location(run.parent_run) if handed_back?
 
       render_completion
     end
@@ -31,6 +34,10 @@ module EasyFlow
 
     private
 
+    def handed_back?
+      run&.parent_run && run.parent_run.waiting_on != run
+    end
+
     def go_back
       guide = runner_for(running_definition)
       loop do

data/app/models/easy_flow/digest.rb

@@ -126,12 +126,16 @@ module EasyFlow
           latest_times[cursor.id] = times[key] if times.key?(key)
           answered += 1 if step_type(cursor)&.awaits_input?
         end
-        cursor = successor(cursor, state.merge(latest), latest_times)
+        cursor = successor(cursor, reached(state, recorded).merge(latest), latest_times)
       end
 
       [ recorded, nil ]
     end
 
+    def reached(state, recorded)
+      state.reject { |key, _value| step(key) && !recorded.include?(key) }
+    end
+
     def records_a_value?(node)
       type = step_type(node)
       type.present? && (type.awaits_input? || type.acts? || type.waits?)

data/app/models/easy_flow/steps/fill_in_the_blank.rb

@@ -0,0 +1,25 @@
+module EasyFlow
+  module Steps
+    class FillInTheBlank
+      include Step
+
+      Asked = Data.define(:id, :text)
+
+      step_name "Fill in the blank"
+
+      setting :question, type: :string
+      setting :category, type: :string
+      setting :required, type: :boolean
+      setting :accepted_answers, type: :list, required: true do
+        setting :value, type: :string
+      end
+
+      names_by :question
+      awaits_input
+      drawn_by "easy_flow/steps/typing"
+      answer_check { |node, value| "Type an answer to go on." if node.config["required"] && value.blank? }
+
+      displays_by { |node| Asked.new(id: node.id.to_sym, text: node.config["question"]) }
+    end
+  end
+end

data/app/models/easy_flow/steps/multiple_select.rb

@@ -0,0 +1,25 @@
+module EasyFlow
+  module Steps
+    class MultipleSelect
+      include Step
+
+      step_name "Multiple select"
+
+      setting :question, type: :string
+      setting :category, type: :string
+      setting :required, type: :boolean
+      setting :answers, type: :list, required: true do
+        setting :value, type: :string
+        setting :label, type: :string
+        setting :weight, type: :integer
+      end
+
+      names_by :question
+      awaits_input
+      drawn_by "easy_flow/steps/ticking"
+      answer_check { |node, value| "Pick at least one answer to go on." if node.config["required"] && Array(value).compact_blank.empty? }
+
+      displays_by { |node| Asked.new(id: node.id.to_sym, text: node.config["question"], choices: Question.choices_in(node)) }
+    end
+  end
+end

data/app/views/easy_flow/steps/_typing.html.erb

@@ -0,0 +1,4 @@
+<label class="block">
+  <span class="ks-section-title mb-5 block text-xl font-semibold leading-snug"><%= step.text %></span>
+  <%= ui_input(name: "answers[#{step.id}]") %>
+</label>

data/lib/easy_flow/engine.rb

@@ -20,6 +20,8 @@ module EasyFlow
 
         EasyFlow::Steps::Question.register
         EasyFlow::Steps::Checklist.register
+        EasyFlow::Steps::MultipleSelect.register
+        EasyFlow::Steps::FillInTheBlank.register
         EasyFlow::Steps::FileUpload.register
         EasyFlow::Condition.register
         EasyFlow::Switch.register

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.25.0"
+  VERSION = "0.27.0"
 end

data/the_local/agents/easy_flow-develop.md

@@ -9,7 +9,7 @@ This local follows the steps below exactly and invents none. Where a step names
 
 ## What easy_flow is
 
-A Rails engine for flows an admin draws on a canvas and a visitor runs one step at a time. Each step is an instance of a step type. The engine ships thirteen: start (`:start`), end (`:terminal`, whose one setting is the output an admin writes for a flow that ends there), question (`:question`, a question with a list of answers of which the visitor picks one, which the admin can mark required so a blank answer is refused), checklist (`:checklist`, a question with a list of answers of which the visitor ticks any number, which the admin can mark required so a visitor who ticks nothing is refused), File upload (`:file_upload`, a question the visitor answers by choosing one file from a file upload control labelled with the question text, with an admin setting listing the accepted file types as comma-separated extensions such as `.pdf, .png`, which limits the visitor's file picker to those types and is shown under the control as `Accepts` followed by the list as the admin wrote it, such as `Accepts .pdf, .png`, which the admin can mark required so a visitor who chooses no file is refused, and whose recorded answer is the reference the host's file store returned for the file), five that pick a branch from earlier answers with no code — condition (`:condition`, is or is not a chosen value, where the admin must pick one of the earlier step's outputs and the answer is read from that output when the earlier step recorded several and whole otherwise, so a Condition cannot be completed on a step whose type declares no output), switch (`:switch`, follows the connection labelled with the answer), compare (`:compare`, reads the answer as a number, from the output the admin picks when the earlier step recorded several, and checks it by more than, less than, at least or at most against an amount) and Compare two values (`:compare_two_values`, reads the answers of two earlier steps the admin picks as numbers, reading each from the output the admin picks when that step recorded several, and checks the first by more than, less than, at least, at most or equal to against the second plus an amount the admin may give, a blank amount adding nothing, checking the first against the amount alone when the admin leaves the second step empty, following its `true` or `false` connection, and following `false` when either answer is missing, is an array or is not a number) and All of or Any of (`:all_or_any`, holds a list of comparisons the admin enters and a `Must hold` setting of `all of` or `any of`, where each comparison asks for the same things as a Compare two values step, a step, its output, a comparison, an amount, and an optional second step and its output, and is checked the same way, a comparison with no second step checking the first answer against the amount alone, following its `true` connection when every comparison holds for `all of` or at least one holds for `any of`, and its `false` connection otherwise, including when it holds no comparisons, a comparison whose answer is missing, is an array or is not a number counting as not holding) — Count (`:count`, which acts without the visitor and records a whole number, how many visits to an earlier step the admin picks the run has recorded, counting only visits that gave the answer the admin picks or every visit when the admin picks none, reading that answer from the output the admin picks when the earlier step recorded several, named on the canvas `Count` followed by the earlier step's id and the answer, such as `Count tests failed`, and recording a new count under its own visit key each time a loop reaches it, so a compare step after it can end a loop once the count reaches an amount), Wait (`:wait`, which holds the run until a time worked out from an earlier step the admin picks as `Counting from`; see "Hold a run until a time"), and Flow (`:flow_step`, names another flow of the same host and the number of one of its versions, with one connection for each different output that version's End steps write, and named on the canvas by that flow's title and the version number, such as `Intake, version 2`). On a compare, Compare two values or Count step, and in each comparison of an All of or Any of step, once the admin picks an earlier step, the admin must also pick which of that step's outputs to read: until then the step's card shows `missing setting: output`, `missing setting: other_output` for a Compare two values step's second step, or `missing setting: comparisons <n> output` and `missing setting: comparisons <n> other_output` for the comparison at position `n` counting from 1, and saving the flow as a new version and publishing it are refused. When a stored run stops at a Flow step, a run of the named flow is started on the named version, and the first run waits on the Flow step. When the second run ends with an output, that output is recorded in the first run at the Flow step, and the first run moves on along the connection labelled with that output. When the second run ends with no output, nothing is recorded and the first run stays waiting at the Flow step. On a question and on a checklist the admin can give each answer info, a longer explanation the visitor opens with an info button beside that answer. An admin may connect a step back to an earlier one, so a flow can ask the same question more than once, and each visit's answer is kept. The time each step visit was completed is kept together with its recorded value; see "Read when steps were completed". A File upload step takes a file only in a flow the admin set to save each step. In a flow set to save on finish or to save nothing, a visitor who chooses a file is shown `A file can only be uploaded in a flow that saves its runs.` and cannot go on with it. Before writing a step type to ask for one answer or several, to take a file, to branch on an answer or a number, to branch on how two earlier answers compare, to branch on whether all or any of several comparisons hold, to branch on when an earlier step was completed, to count the visits to an earlier step, or to hold a run until a time, ask the developer whether an admin placing one of the built-in types on the canvas is enough. None of condition, switch, compare, Compare two values or All of or Any of reads a checklist's answer, so branching on what a visitor ticked takes a step type of the app's own that defines `route`. Use this local when the app needs a step type of its own, needs a host's flows on its own pages with its own behaviour when a visitor finishes, needs a visitor's earlier answers to decide which answers a later step offers, or needs to read what a visitor answered. It assumes easy_flow is already installed and a host is declared; if not, hand off to `easy_flow-install` first.
+A Rails engine for flows an admin draws on a canvas and a visitor runs one step at a time. Each step is an instance of a step type. The engine ships fifteen: start (`:start`), end (`:terminal`, whose one setting is the output an admin writes for a flow that ends there), question (`:question`, a question with a list of answers of which the visitor picks one, which the admin can mark required so a blank answer is refused), checklist (`:checklist`, a question with a list of answers of which the visitor ticks any number, which the admin can mark required so a visitor who ticks nothing is refused), Multiple select (`:multiple_select`, a question with a category and a list of answers, each with a value, a label and a weight, of which the visitor ticks any number, recording the list of ticked values, which the admin can mark required so a visitor who ticks nothing is refused with `Pick at least one answer to go on.`), Fill in the blank (`:fill_in_the_blank`, a question with a category and a list of accepted answers, each with a value, which the visitor answers by typing into a text box, recording the text exactly as typed, whose accepted answers are never sent to the visitor's page, which the admin can mark required so a visitor who types nothing or only spaces is refused with `Type an answer to go on.`; easy_flow records the answer and does not mark it right or wrong), File upload (`:file_upload`, a question the visitor answers by choosing one file from a file upload control labelled with the question text, with an admin setting listing the accepted file types as comma-separated extensions such as `.pdf, .png`, which limits the visitor's file picker to those types and is shown under the control as `Accepts` followed by the list as the admin wrote it, such as `Accepts .pdf, .png`, which the admin can mark required so a visitor who chooses no file is refused, and whose recorded answer is the reference the host's file store returned for the file), five that pick a branch from earlier answers with no code — condition (`:condition`, is or is not a chosen value, where the admin must pick one of the earlier step's outputs and the answer is read from that output when the earlier step recorded several and whole otherwise, so a Condition cannot be completed on a step whose type declares no output), switch (`:switch`, follows the connection labelled with the answer), compare (`:compare`, reads the answer as a number, from the output the admin picks when the earlier step recorded several, and checks it by more than, less than, at least or at most against an amount) and Compare two values (`:compare_two_values`, reads the answers of two earlier steps the admin picks as numbers, reading each from the output the admin picks when that step recorded several, and checks the first by more than, less than, at least, at most or equal to against the second plus an amount the admin may give, a blank amount adding nothing, checking the first against the amount alone when the admin leaves the second step empty, following its `true` or `false` connection, and following `false` when either answer is missing, is an array or is not a number) and All of or Any of (`:all_or_any`, holds a list of comparisons the admin enters and a `Must hold` setting of `all of` or `any of`, where each comparison asks for the same things as a Compare two values step, a step, its output, a comparison, an amount, and an optional second step and its output, and is checked the same way, a comparison with no second step checking the first answer against the amount alone, following its `true` connection when every comparison holds for `all of` or at least one holds for `any of`, and its `false` connection otherwise, including when it holds no comparisons, a comparison whose answer is missing, is an array or is not a number counting as not holding) — Count (`:count`, which acts without the visitor and records a whole number, how many visits to an earlier step the admin picks the run has recorded, counting only visits that gave the answer the admin picks or every visit when the admin picks none, reading that answer from the output the admin picks when the earlier step recorded several, named on the canvas `Count` followed by the earlier step's id and the answer, such as `Count tests failed`, and recording a new count under its own visit key each time a loop reaches it, so a compare step after it can end a loop once the count reaches an amount), Wait (`:wait`, which holds the run until a time worked out from an earlier step the admin picks as `Counting from`; see "Hold a run until a time"), and Flow (`:flow_step`, names another flow of the same host and the number of one of its versions, with one connection for each different output that version's End steps write, and named on the canvas by that flow's title and the version number, such as `Intake, version 2`). On a compare, Compare two values or Count step, and in each comparison of an All of or Any of step, once the admin picks an earlier step, the admin must also pick which of that step's outputs to read: until then the step's card shows `missing setting: output`, `missing setting: other_output` for a Compare two values step's second step, or `missing setting: comparisons <n> output` and `missing setting: comparisons <n> other_output` for the comparison at position `n` counting from 1, and saving the flow as a new version and publishing it are refused. When a stored run stops at a Flow step, a run of the named flow is started on the named version, and the first run waits on the Flow step. When the second run ends with an output, that output is recorded in the first run at the Flow step, and the first run moves on along the connection labelled with that output. When the second run ends with no output, nothing is recorded and the first run stays waiting at the Flow step. On a question and on a checklist the admin can give each answer info, a longer explanation the visitor opens with an info button beside that answer. An admin may connect a step back to an earlier one, so a flow can ask the same question more than once, and each visit's answer is kept. The time each step visit was completed is kept together with its recorded value; see "Read when steps were completed". A File upload step takes a file only in a flow the admin set to save each step. In a flow set to save on finish or to save nothing, a visitor who chooses a file is shown `A file can only be uploaded in a flow that saves its runs.` and cannot go on with it. Before writing a step type to ask for one answer or several, to take a file, to branch on an answer or a number, to branch on how two earlier answers compare, to branch on whether all or any of several comparisons hold, to branch on when an earlier step was completed, to count the visits to an earlier step, or to hold a run until a time, ask the developer whether an admin placing one of the built-in types on the canvas is enough. None of condition, switch, compare, Compare two values or All of or Any of reads a checklist's answer, so branching on what a visitor ticked takes a step type of the app's own that defines `route`. Use this local when the app needs a step type of its own, needs a host's flows on its own pages with its own behaviour when a visitor finishes, needs a visitor's earlier answers to decide which answers a later step offers, or needs to read what a visitor answered. It assumes easy_flow is already installed and a host is declared; if not, hand off to `easy_flow-install` first.
 
 ## Interface
 
@@ -36,7 +36,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - It only picks which connection to follow — define `route`.
    - It holds the visitor until something outside the flow has happened, such as a payment arriving or a reviewer approving — declare `waits_until`. When what it waits for is only a time, ask the developer whether the built-in Wait step is enough first; see "Hold a run until a time".
    A type may both `process` and `route`. A type that does none of the four is passed through without stopping when a visitor reaches it.
-2. Create the class in the app, for example `app/models/flow_steps/rating.rb`. The class name, underscored, is the type's id (`Rating` becomes `:rating`), and that id is stored in every flow that uses it, so it must not change after admins start using the type. It must not be one of the built-in ids `start`, `terminal`, `question`, `checklist`, `file_upload`, `condition`, `switch`, `compare`, `compare_two_values`, `all_or_any`, `count`, `wait` or `flow_step`:
+2. Create the class in the app, for example `app/models/flow_steps/rating.rb`. The class name, underscored, is the type's id (`Rating` becomes `:rating`), and that id is stored in every flow that uses it, so it must not change after admins start using the type. It must not be one of the built-in ids `start`, `terminal`, `question`, `checklist`, `multiple_select`, `fill_in_the_blank`, `file_upload`, `condition`, `switch`, `compare`, `compare_two_values`, `all_or_any`, `count`, `wait` or `flow_step`:
 
    ```ruby
    module FlowSteps
@@ -366,7 +366,7 @@ Use this when a visitor's run reaches a Flow step and the app must take the visi
    - The new run is moved on at once past every step that acts without the visitor, the same as `run.advance`. When it stops at a Flow step of its own, that starts a further run the same way.
    - It is started once per visit to the step, so loading the page again or calling `advance` again starts no second one.
    - Its `owner` is the parent run's `owner` at the moment the new run is started, or blank when the parent run has none. Setting or changing the parent run's owner later does not change it. Its `label` and `status` are not copied and are left blank.
-   - The parent run shows the visitor `Waiting for <name>.`, where the built-in Flow step's name is the named flow's title and version number, such as `Waiting for Intake, version 2.`, with no form, no Next button and no Back button, and stays on the Flow step until the new run ends.
+   - A visitor who loads the parent run's page is redirected to the new run's page, at the controller's own run address from `run_address`, and shown its first unanswered step. This holds whenever the parent run is stopped at the Flow step, so a visitor who opens the parent run's address while the new run is unfinished is sent to the new run. The parent run stays on the Flow step until the new run ends.
    - A flow set to save on finish or to save nothing, and an admin's preview, keep no stored run, so they start no run at a Flow step.
    - A flow cannot be published while one of its Flow steps names a missing flow, a version that cannot run, or a flow that leads back to it. A flow or version can still stop being runnable after the flow holding the step was published, such as a named flow being deleted or its version retired or withdrawn. Then, at the moment the run stops at the Flow step, one of these is raised and no run is started:
      - `ActiveRecord::RecordNotFound` when the named flow is gone.
@@ -378,19 +378,19 @@ Use this when a visitor's run reaches a Flow step and the app must take the visi
    - A job is queued with the app's Active Job adapter, on the `default` queue, that calls `advance` on the parent run. The parent run also moves on the next time its own page is loaded, whichever comes first, so a parent run whose job never runs still moves on when its visitor reloads.
    - The parent run follows the connection leaving the Flow step labelled with that output. An output that matches no connection's label ends the parent run at the Flow step.
    - When the parent run then ends and was itself started by a Flow step, its own output is handed to its parent the same way.
-   - The new run's own `finished` is still called on its visitor's page load. The job does not call `finished` for the parent run, and if the parent run reaches its end, `finished` is called the next time its visitor loads its page.
-   - A visitor who presses Back on the step after a Flow step removes the recorded output, and the parent run waits on the Flow step again. No second run is started, and the parent run moves on again only when the new run's page is loaded or `advance` is called on it.
+   - The new run's visitor is redirected to the parent run's page, at the controller's own run address, and the new run's own `finished` is not called. The parent run's page moves the parent run on itself without waiting for the job, then shows its next step, redirects into the next inner run when it stops at another Flow step, or calls the parent run's `finished` when it has ended. The job does not call `finished` for the parent run.
+   - A visitor who presses Back on the step after a Flow step removes the recorded output, and the parent run waits on the Flow step again. No second run is started. The parent run's page then redirects the visitor to the ended new run, whose page hands its output back again and redirects the visitor to the same step after the Flow step, so Back does not take a visitor past a Flow step.
 4. What holds when the new run ends with no output, which happens when it ends on an End step whose output was left blank, or ends without reaching an End step for any reason other than a loop stopping it, and the step that started it is not of a type that declares `chooses_flow_from_run` (for that type, `"ended"` is recorded and the parent run moves on):
-   - Nothing is recorded in the parent run, and the parent run stays at the Flow step showing `Waiting for <name>.` on every page load. Nothing in the engine moves it on.
+   - Nothing is recorded in the parent run, and the parent run stays at the Flow step, so loading its page redirects the visitor to the new run. Nothing in the engine moves it on.
    - A job is still queued that fails with `EasyFlow::InnerFlowError` and a message naming the Flow step's id, such as `Nothing was recorded at the Flow step sub, so its run cannot move on`. The job does not move the parent run.
    - Each later page load of the new run, and each later `advance` on it, queues another job that fails the same way.
    - What happens to a failed job, such as a retry or a report, is decided by the app's Active Job adapter and error reporting.
-   - The new run's own `finished` is still called on its visitor's page load.
+   - The new run's visitor is not sent back to the parent run, and the new run's own `finished` is still called on its visitor's page load.
 5. What holds when a loop stops the new run, which is when `inner.stopped_on_loop` names a step (see "Read a run and its answers"), whatever type the step that started it is:
    - Nothing is recorded in the parent run, not even `"ended"` for a step of a type that declares `chooses_flow_from_run`.
    - No job is queued, on the page load that stops the new run or on any later page load or `advance` of it, so no `EasyFlow::InnerFlowError` is raised for it.
-   - The parent run stays at the step showing `Waiting for <name>.` on every page load, and `parent.waiting_on` is still the stopped run. Nothing in the engine moves it on.
-   - The new run's own `finished` is still called on its visitor's page load.
+   - The parent run stays at the step, so loading its page redirects the visitor to the stopped run, and `parent.waiting_on` is still the stopped run. Nothing in the engine moves it on.
+   - The new run's visitor is not sent back to the parent run, and the new run's own `finished` is still called on its visitor's page load.
 6. What holds when an admin removes a flow:
    - Every run of the removed flow is deleted with it.
    - A run that one of those runs' Flow steps started is kept. Its `parent_run` becomes `nil` and its `parent_step` keeps the step id.
@@ -534,7 +534,7 @@ Use this when a visitor's run should stop until a set time has passed, such as a
 ## Conventions
 
 - A step type's id comes from its class name or the id passed to `EasyFlow.step`, and it is stored in flow documents, so renaming the class or id breaks every flow that uses it.
-- Never give a step type one of the built-in ids: `start`, `terminal`, `question`, `checklist`, `file_upload`, `condition`, `switch`, `compare`, `compare_two_values`, `all_or_any`, `count`, `wait`, `flow_step`.
+- Never give a step type one of the built-in ids: `start`, `terminal`, `question`, `checklist`, `multiple_select`, `fill_in_the_blank`, `file_upload`, `condition`, `switch`, `compare`, `compare_two_values`, `all_or_any`, `count`, `wait`, `flow_step`.
 - Register class-based step types inside `to_prepare`. A type registered anywhere else is lost on code reload in development.
 - Registering a type does not put it in the palette of a host that names a list of offered step types without the type's id. Which step types a host offers is set through `easy_flow-install`, not here.
 - A type that declares `ends_here` is in every host's palette, and a type that declares `begins_here` is in no host's palette.

data/the_local/agents/easy_flow-info.md

@@ -11,7 +11,7 @@ This local explains easy_flow and the words it uses. It makes no changes and giv
 
 easy_flow is a Rails engine for guided, branching flows. An admin builds a flow on a canvas by placing steps and connecting them, previews it, and publishes it. A visitor then walks the published flow one step at a time, and each answer decides which step comes next.
 
-Reach for it when an app needs a questionnaire, an intake form, or any decision path that an admin should be able to change without a deploy. The engine ships a start step, an end step, a question step, a checklist step, a file upload step, five steps that pick a branch from earlier answers, a Count step that counts earlier answers, a Wait step that holds a run until a time, and a Flow step that names another flow. Anything else a flow needs to ask, do, or wait for is a step type the app declares itself.
+Reach for it when an app needs a questionnaire, an intake form, or any decision path that an admin should be able to change without a deploy. The engine ships a start step, an end step, a question step, a checklist step, a multiple select step, a fill in the blank step, a file upload step, five steps that pick a branch from earlier answers, a Count step that counts earlier answers, a Wait step that holds a run until a time, and a Flow step that names another flow. Anything else a flow needs to ask, do, or wait for is a step type the app declares itself.
 
 ## Interface
 
@@ -60,6 +60,8 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Flow output** — the text an admin writes into the output setting of an End step, given as the result of a stored run that has reached that step. A flow may hold several End steps with a different output on each, so the output says which way the flow ended. A run that has not reached an End step, or that ended on one whose output was left blank, gives no output.
 - **Question** — the built-in step type that asks the visitor: a question text, an optional category, a yes-or-no required setting, and a list of answers, each with a value, a label, a weight, a hint and an info. The visitor picks one answer, and that answer's value is recorded.
 - **Checklist** — the built-in step type that asks the visitor to tick any number of answers: a question text, a yes-or-no required setting, and a list of answers, each with a value, a label and an info. The list of ticked values is recorded, and a checklist left with nothing ticked records an empty list.
+- **Multiple select** — the built-in step type that asks the visitor to tick any number of answers, for a question that has several right answers: a question text, a category, a yes-or-no required setting, and a list of answers, each with a value, a label and a weight. The list of ticked values is recorded, and a required one left with nothing ticked is refused with the message "Pick at least one answer to go on."
+- **Fill in the blank** — the built-in step type that asks the visitor to type an answer: a question text, a category, a yes-or-no required setting, and a list of accepted answers. The text typed is recorded as typed, the accepted answers are never sent to the visitor's page, and a required one left blank is refused with the message "Type an answer to go on." easy_flow does not mark the typed answer right or wrong.
 - **File upload** — the built-in step type that asks the visitor for one file: a question text, the accepted file types, and a yes-or-no required setting. The accepted file types are a comma-separated list of extensions, such as `.pdf, .png`, and an empty list accepts any file. The visitor sees a styled file upload control labelled with the question text. When accepted file types are set, the visitor's file picker offers only those types, and a line under the control reads "Accepts" followed by the list exactly as the admin wrote it, such as "Accepts .pdf, .png". A file whose extension is not on the list is refused with a message naming the accepted types, such as "Choose a .pdf or .png file.", and is not handed to the file store. A required file upload left empty is refused with "Choose a file to go on." A file can only be uploaded in a flow that keeps a stored run, so a flow that carries its answers in the page refuses one with "A file can only be uploaded in a flow that saves its runs."
 - **File store** — the object the app sets to keep uploaded files. It takes an accepted file, keeps it, and returns a reference, and that reference is what the run records as the step's answer. When a step's answer is sent as a list holding several files, such as from a step type of the app's own, each file is handed to the store and the run records the list of references. It also gives the name of the file a reference points to, which is what the read-back shows. When a file is accepted and the app has set no file store, the step fails with an error saying a file store must be set.
 - **Hint** — a short line of text shown under an answer's label on a question step.
@@ -77,13 +79,13 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Wait** — a built-in waiting step that holds a run until a time. The admin picks the earlier step it counts from and gives a number of minutes after it, a time of day as HH:MM, or a date as YYYY-MM-DD. A date holds the run until the start of that day in the app's time zone and wins over the other two, and it holds even when the earlier step has no completion time. Otherwise a time of day holds the run until the next time that time of day comes after the earlier step's completion time, the same day when it is still to come and the next day when it is not, and it wins over minutes. With neither, the run is held for the minutes after the earlier step's completion time, and blank minutes hold it not at all. While the earlier step has no completion time and no date is set, the run stays held. It is counted from the completion time of the latest visit to that step. Like any waiting step, once its time has come the run moves past it the next time the visitor's page is loaded or the app moves the run on.
 - **Wait step name** — what a Wait step is called on its canvas card and in the "Waiting for" line a visitor sees, following the same order as the rule that holds the run. A date set names it by that date, such as "2026-12-01". Otherwise it is named by the time of day, or by the minutes followed by "minutes", then "after" and the earlier step, such as "09:00 after signup" or "30 minutes after signup", with "minute" in place of "minutes" when the number is 1, such as "1 minute after signup". A Wait step with no date, time of day or minutes has no name of its own, so its canvas card shows the step's id and the visitor sees "Waiting for Wait".
 - **Count** — a built-in step that acts on its own and records a whole number: how many visits to an earlier step the run has recorded. When the admin picks an answer, only visits that gave that answer are counted, and when the admin picks none, every visit is counted. The admin picks which of the earlier step's outputs the answer is read from, as described under chosen output. On the canvas the step is named "Count" followed by the earlier step and the answer it counts, such as "Count tests failed". Each visit to a Count step in a loop records a new count under its own visit key, so a Compare step after it can end the loop once the count reaches an amount.
-- **Flow step** — a built-in step that names another flow and the number of one of its versions. The admin picks the flow from the same host's flows, listed by title as the admin's list of flows shows them. The step has one connection for each different output the End steps of that version write, and none when no flow or version is picked or no End step there has an output. On the canvas its card is named after the flow's title and the version, such as "Onboarding, version 2", and is marked "Runs a flow". Once a flow is picked, clicking the card opens that flow's canvas, and the card's Settings button opens the step's own settings instead. A canvas opened from a Flow step's card shows a "Back to" button named after the title of the flow it was opened from, or its slug when it has no title, which returns to that flow's canvas. The button only appears when that flow belongs to the same host, and to the same owner when the host has one. While the admin is connecting steps, clicking the card picks it as the connection's target. A run that reaches a Flow step stops there. When the run is a stored run, it starts one inner run of the named flow on the picked version. A run that carries its answers in the page, and an admin's preview, stop at the Flow step, start no run, and never move past it.
+- **Flow step** — a built-in step that names another flow and the number of one of its versions. The admin picks the flow from the same host's flows, listed by title as the admin's list of flows shows them. The step has one connection for each different output the End steps of that version write, and none when no flow or version is picked or no End step there has an output. On the canvas its card is named after the flow's title and the version, such as "Onboarding, version 2", and is marked "Runs a flow". Once a flow is picked, clicking the card opens that flow's canvas, and the card's Settings button opens the step's own settings instead. A canvas opened from a Flow step's card shows a "Back to" button named after the title of the flow it was opened from, or its slug when it has no title, which returns to that flow's canvas. The button only appears when that flow belongs to the same host, and to the same owner when the host has one. While the admin is connecting steps, clicking the card picks it as the connection's target. A run that reaches a Flow step stops there. When the run is a stored run, it starts one inner run of the named flow on the picked version, and a visitor on the run's page is taken to that inner run's first unanswered step. A run that carries its answers in the page, and an admin's preview, stop at the Flow step, start no run, and never move past it.
 - **Unrunnable Flow step** — a Flow step whose picked flow or version cannot be run. Its card shows "missing flow" when no flow is picked or the picked flow no longer exists, and "unrunnable version" when the picked flow has no version with that number or that version is a draft, retired or withdrawn. These are always on, unlike the optional checks below, and the flow holding such a step cannot be saved as a new version or published until it is fixed.
 - **Circular Flow step** — a Flow step that leads back to the flow it sits in. That is either a Flow step naming its own flow, or one naming a flow whose picked version holds a Flow step that leads back the same way, through any number of flows. Each flow along the way is read at the version its Flow step picked. Its card shows "circular", and like an unrunnable Flow step this is always on and keeps the flow from being saved as a new version or published until it is fixed.
 - **Flow-starting step type** — a step type of the app's own that starts another flow the way the Flow step does. By default it runs the flow and version named in its settings called flow and version. It may instead carry a rule that works out the flow and version from its other settings, and that choice is then used everywhere a Flow step's choice is: starting the inner run, the unrunnable and circular checks, and the canvas link to that flow. When the step type gives the step no name of its own, the step is named after the flow and version that rule works out, the same way a Flow step is, such as "Onboarding, version 2", on its canvas card and in the "Waiting for" line a visitor sees. Everything said below about a Flow step's inner run and handing back applies to it too, except where a run-chosen flow says otherwise.
 - **Run-chosen flow** — a flow-starting step type of the app's own that chooses the flow and version from the run it is in rather than from its settings, so two runs of one flow can start two different inner flows from the same step. Where there is no run, such as on the canvas, it has no chosen flow. Its steps are left out of the unrunnable and circular checks, so a flow holding one can be published with no flow in its settings. A run that reaches it and has no flow chosen fails with an error naming the step. When its inner run ends with no output, the step records `ended` and its run moves on.
 - **Inner run** — the run a Flow step starts. It records which run started it and at which step, and that run holds at most one inner run for each Flow step, however often it is moved on. It belongs to the same owner as the run that started it. When the picked version has been retired or withdrawn, no inner run is started and the run that reached the Flow step fails with an error naming that step. While the run that started it is stopped at the Flow step, that run can name the inner run it is waiting on, and it names none when it is stopped at any other step or has finished. Its steps that act on their own run as soon as it starts, and it stops at its first step that asks for input or waits.
-- **Handing back** — what happens when an inner run ends. Its flow output is recorded in the run that started it, as that run's answer at the Flow step, and a background job then moves that run on along the connection labelled with the output. An inner run that ended with no output records nothing in the run that started it, and the background job then fails with an error naming the Flow step, so that run does not move on. An inner run that a loop stopped hands nothing back and starts no background job, so the run that started it stays stopped at the Flow step and still names that inner run as the one it is waiting on. An output is handed back only once, so an inner run moved on again after it ended changes nothing. Because the move happens in a background job, the app must run its jobs for a run to go past a Flow step.
+- **Handing back** — what happens when an inner run ends. Its flow output is recorded in the run that started it, as that run's answer at the Flow step, and a background job then moves that run on along the connection labelled with the output. The inner run's visitor is taken back to the run that started it, whose page moves it on without waiting for the job and shows its next step. An inner run that ended with no output records nothing in the run that started it, and the background job then fails with an error naming the Flow step, so that run does not move on. An inner run that a loop stopped hands nothing back and starts no background job, so the run that started it stays stopped at the Flow step and still names that inner run as the one it is waiting on. An output is handed back only once, so an inner run moved on again after it ended changes nothing. Because the move otherwise happens in a background job, the app must run its jobs for a run nobody is visiting to go past a Flow step.
 - **Waiting step** — a step whose type carries a rule saying whether what it waits for has happened, such as a payment clearing or a document being signed. A run that reaches it stops there, and the visitor sees "Waiting for" followed by the step's name, with no form to submit. Once the rule says it has happened, the run moves past the step the next time the visitor's page is loaded or the app moves the run on, and the step is recorded as `true`.
 - **Check again** — a button a visitor sees under the "Waiting for" line in a flow that carries its answers in the page. It loads the step page again with the answers and their completion times, so the run moves past a waiting step whose rule now says it has happened, such as a Wait step whose time has come. A stored run shows no such button, since loading its page again does the same.
 - **Registry** — the list of step types the app has registered, alongside the built-in ones. A step whose type is not registered is not shown or run as that type, and its answers are not checked.
@@ -95,7 +97,7 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Stored run** and **carried answers** — the two ways a visitor's progress is held. A stored run is saved by the app and found again by its id. A flow that keeps nothing carries the answers given so far, and their completion times, in the page itself and sends them along with each step.
 - **Visit entry** — what a stored run keeps for one visit: the value the step recorded and the step's completion time, held together as one entry. Reading a run's answers gives each visit's value, and reading its completion times gives each visit's time. A run stored before entries existed holds bare values, and the engine's migration wraps each one in an entry with no completion time, and running that migration back unwraps them.
 - **Answers** — the recorded values of a run, keyed by visit. The next step is always worked out from these values, their completion times and the connections in the pinned version.
-- **Loop** — a connection that leads back to a step the run has already passed, so that step is visited again. Branching steps read the most recent answer to a step, so a loop ends when an answer sends the run down a different connection. Reading a finished run again follows the same connections it took at the time, since each branching step reads the answers as they stood at that visit.
+- **Loop** — a connection that leads back to a step the run has already passed, so that step is visited again. Branching steps read the most recent answer to a step recorded before them on the run's path, and never an answer a step further along recorded, so a loop ends when an answer sends the run down a different connection. Reading a finished run again follows the same connections it took at the time, since each branching step reads the answers as they stood at that visit.
 - **Visit** — one time a run reaches a step. The first visit is keyed by the step id alone, and each later visit is keyed by the step id, an `@`, and the visit number, such as `size@2`. Every visit's value and completion time are kept, and a finished run lists each one.
 - **Stopped loop** — a run that comes back to a step with no new answer given since its last visit there ends at that point rather than cycling forever. Only answers the visitor gives count, so a loop made only of steps that act on their own stops the first time it comes round. A stored run stopped this way names the step the loop came back to, and does not count as having ended at an End step. An inner run stopped this way leaves the run that started it at its Flow step, as described under handing back.
 - **Ended at an End step** — whether a stored run's path finished on an End step, or on a step of the app's own type that ends a flow. It does not while the run is still going or held at a step, when a loop stopped it, or when it stopped at a step with no connection to follow.

data/the_local/agents/easy_flow-install.md

@@ -45,7 +45,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
      host.visitor_authorization_method = :easy_flow_visitor_permitted?
      host.refusal_method = :refuse_flow
      host.owner_method = :current_account
-     host.offers = %i[question checklist file_upload condition switch compare compare_two_values all_or_any count wait flow_step]
+     host.offers = %i[question checklist multiple_select fill_in_the_blank file_upload condition switch compare compare_two_values all_or_any count wait flow_step]
    end
    ```
 
@@ -55,7 +55,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `visitor_authorization_method` — a method on the base controller, called with the flow, returning true when the visitor may run it. With none set, every visitor is refused.
    - `refusal_method` — a method on the base controller, called with the refusal error when a visitor is refused or a flow is unpublished or withdrawn. With none set, the response is `404 Not Found`.
    - `owner_method` — a method on the base controller, called with no arguments, returning the record whose flows the current request works with, such as the signed-in account. When set, the admin pages list, create and edit only that record's flows, a visitor runs only that record's flows, and two records may each hold a flow with the same slug. With none set, every flow in the host is shared by everyone who reaches it. Ask the developer whether each host's flows belong to one record or are shared.
-   - `offers` — the step types this host's admins can add from the canvas palette, as a list of step type names. With none set, every registered step type is offered. The engine's own names are `question`, `checklist`, `file_upload`, `condition`, `switch`, `compare`, `compare_two_values`, `all_or_any`, `count`, `wait` and `flow_step`, `file_upload` being the File upload step, which needs the file store from step 10, `compare_two_values` being the Compare two values step, which compares the outputs of two earlier steps, `all_or_any` being the All of or Any of step, which decides whether all or any of several such comparisons hold, `count` being the Count step, which counts how often an earlier step was answered, `wait` being the Wait step, which holds a run until a time counted from an earlier answer or until a date, and `flow_step` being the Flow step, which names one of the same host's flows. A step type the app declares is named by the id it was declared with, or after its class when it is a step class, so `Steps::Notify` is `notify`. The End step is offered whether it is listed or not, and the Start step is never offered. Ask the developer which step types each host should offer.
+   - `offers` — the step types this host's admins can add from the canvas palette, as a list of step type names. With none set, every registered step type is offered. The engine's own names are `question`, `checklist`, `multiple_select`, `fill_in_the_blank`, `file_upload`, `condition`, `switch`, `compare`, `compare_two_values`, `all_or_any`, `count`, `wait` and `flow_step`, `file_upload` being the File upload step, which needs the file store from step 10, `compare_two_values` being the Compare two values step, which compares the outputs of two earlier steps, `all_or_any` being the All of or Any of step, which decides whether all or any of several such comparisons hold, `count` being the Count step, which counts how often an earlier step was answered, `wait` being the Wait step, which holds a run until a time counted from an earlier answer or until a date, and `flow_step` being the Flow step, which names one of the same host's flows. A step type the app declares is named by the id it was declared with, or after its class when it is a step class, so `Steps::Notify` is `notify`. The End step is offered whether it is listed or not, and the Start step is never offered. Ask the developer which step types each host should offer.
 
    Each method named here must exist on the base controller. Ask the developer to point at it or write it. Do not invent its logic.
 8. Mount the engine in `config/routes.rb`, once per host. The host name in `defaults` must match a name declared in step 7. When there is more than one mount, give each an `as:` name:
@@ -89,7 +89,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
     - The store answers `name_of(reference)`, called with a reference `keep` returned. It returns the name the visitor's completion page shows for that answer. When it returns nothing, the page shows the reference itself.
     - With no store set, a visitor who submits a file at any step of a stored run gets the app's error page, raised as `EasyFlow::NoFileStore`.
 11. Leave `EasyFlow.check` out unless the developer asks for it. The engine already turns on `:unrouted_value`, `:unfollowed_path` and `:dead_end` at boot. Any other name raises `EasyFlow::UnknownCheck` when the app boots.
-12. Check that the app loads Active Job (`require "rails/all"` or `require "active_job/railtie"` in `config/application.rb`) and has a queue adapter that runs jobs from the `default` queue. When a run started by a Flow step, or by a step type of the app's own that starts another flow, ends, the engine records its output in the run it was started from and queues a job on `default` that moves that run on. If no adapter runs that queue, the run that holds the step stays at it. If `config.active_job.queue_adapter` is not set for an environment, ask the developer which adapter to use there.
+12. Check that the app loads Active Job (`require "rails/all"` or `require "active_job/railtie"` in `config/application.rb`) and has a queue adapter that runs jobs from the `default` queue. When a run started by a Flow step, or by a step type of the app's own that starts another flow, ends, the engine records its output in the run it was started from and queues a job on `default` that moves that run on. If no adapter runs that queue, the run that holds the step stays at it until its visitor next loads its page. If `config.active_job.queue_adapter` is not set for an environment, ask the developer which adapter to use there.
 13. Check `config.time_zone` in `config/application.rb`. A Wait step's time of day and date, and the "Hour completed" and "Weekday completed" outputs every completed step offers, are read in that zone, and with none set it is UTC. If it is not set, ask the developer which zone the app's admins mean when they write a time.
 14. Start the server and open `<mount path>/manage/flows` for each host.
 

data/the_local/interface.yml

@@ -41,6 +41,8 @@ sources:
   - app/models/easy_flow/terminal.rb
   - app/models/easy_flow/steps/question.rb
   - app/models/easy_flow/steps/checklist.rb
+  - app/models/easy_flow/steps/multiple_select.rb
+  - app/models/easy_flow/steps/fill_in_the_blank.rb
   - app/models/easy_flow/steps/file_upload.rb
   - app/models/easy_flow/count.rb
   - app/models/easy_flow/compare_two_values.rb
@@ -60,6 +62,7 @@ sources:
   - app/views/easy_flow/flows/complete.html.erb
   - app/views/easy_flow/steps/_choosing.html.erb
   - app/views/easy_flow/steps/_ticking.html.erb
+  - app/views/easy_flow/steps/_typing.html.erb
   - app/views/easy_flow/steps/_uploading.html.erb
   - app/controllers/easy_flow/manage/previews_controller.rb
   - config/routes.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_flow
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - tylercschneider
@@ -137,6 +137,8 @@ files:
 - app/models/easy_flow/step_type/declaration.rb
 - app/models/easy_flow/steps/checklist.rb
 - app/models/easy_flow/steps/file_upload.rb
+- app/models/easy_flow/steps/fill_in_the_blank.rb
+- app/models/easy_flow/steps/multiple_select.rb
 - app/models/easy_flow/steps/question.rb
 - app/models/easy_flow/switch.rb
 - app/models/easy_flow/terminal.rb
@@ -155,6 +157,7 @@ files:
 - app/views/easy_flow/manage/versions/index.html.erb
 - app/views/easy_flow/steps/_choosing.html.erb
 - app/views/easy_flow/steps/_ticking.html.erb
+- app/views/easy_flow/steps/_typing.html.erb
 - app/views/easy_flow/steps/_uploading.html.erb
 - app/views/layouts/easy_flow/application.html.erb
 - config/routes.rb