easy_flow 0.32.1 → 0.34.0

data/app/models/easy_flow/change.rb

@@ -1,12 +1,22 @@
 module EasyFlow
   module Change
     PHRASING = { "added" => "Added", "updated" => "Updated", "removed" => "Removed",
-                 "moved" => "Moved", "connected" => "Connected", "disconnected" => "Disconnected", "returned" => "Returned to" }.freeze
+                 "moved" => "Moved", "connected" => "Connected", "disconnected" => "Disconnected", "returned" => "Returned to",
+                 "removed_unconnected" => "Removed unconnected" }.freeze
+
+    def self.listed(changes)
+      changes.chunk_while { |earlier, later| saves_to_one_step?(earlier, later) }.map { |saves| phrase(saves.last) }
+    end
+
+    def self.saves_to_one_step?(earlier, later)
+      earlier["action"] == "updated" && later["action"] == "updated" && earlier["steps"] == later["steps"]
+    end
 
     def self.phrase(change)
       named = Array(change["named"]).compact_blank.map { |name| "“#{name}”" }
       verb = PHRASING.fetch(change["action"], change["action"])
 
+      return "#{verb} #{named.join(', ')}" if named.any? && change["action"] == "removed_unconnected"
       return "#{verb} #{named.join(' → ')}" if named.any?
       return "#{verb} #{change['detail']}" if change["detail"].present?
 

data/app/models/easy_flow/data_step.rb

@@ -0,0 +1,33 @@
+module EasyFlow
+  module DataStep
+    extend ActiveSupport::Concern
+    include Inputs
+
+    included do
+      names_by :data
+      needs_a_saved_run "Data can only be read or written in a flow that saves its runs."
+
+      setting(:values, type: :list, label: "Values it reports") { setting :name, type: :string, required: true }
+      outputs_named_by :values
+
+      output :result, values: %w[passed failed]
+      output :reason
+      output :answer
+    end
+
+    def process(node, state)
+      raise ArgumentError, "#{node.config["data"]} is not offered by this step" unless self.class.step_type.settings.choices[:data].include?(node.config["data"])
+
+      answer = ActiveRecord::Base.transaction(requires_new: true) do
+        EasyFlow.data_source.carry_out(node.config["data"], Inputs.values_of(node, state))
+      end.as_json
+      (answer.is_a?(Hash) ? answer : { "answer" => answer }).merge("result" => "passed")
+    rescue => error
+      { "result" => "failed", "reason" => error.message }
+    end
+
+    def route(node, state)
+      state.dig(node.id, "result")
+    end
+  end
+end

data/app/models/easy_flow/definition.rb

@@ -61,6 +61,11 @@ module EasyFlow
       update!(undo_history: edit_history.undoable, changes_since_version: [], undone_changes: [])
     end
 
+    def remove_unconnected(steps)
+      create_version
+      edit_history.record(Document.new(document).without(steps), :removed_unconnected, steps, document)
+    end
+
     def returning_to(version)
       { "action" => "returned", "steps" => [], "named" => [],
         "detail" => "version #{version.number}", "before" => document }

data/app/models/easy_flow/document.rb

@@ -47,6 +47,12 @@ module EasyFlow
       found
     end
 
+    def unconnected
+      return [] unless entry
+
+      nodes.map(&:id).uniq - reachable - beginnings
+    end
+
     def to_h
       @document
     end
@@ -103,6 +109,11 @@ module EasyFlow
            edges: (raw_edges - incoming - outgoing) + bridges(incoming, outgoing))
     end
 
+    def without(ids)
+      Document.new(@document.merge("nodes" => raw_nodes.reject { |node| ids.include?(node["id"]) },
+        "edges" => raw_edges.reject { |edge| ids.include?(edge["from"]) || ids.include?(edge["to"]) }), registry: @registry)
+    end
+
     private
 
     def bridges(incoming, outgoing)

data/app/models/easy_flow/inputs.rb

@@ -0,0 +1,24 @@
+module EasyFlow
+  module Inputs
+    extend ActiveSupport::Concern
+
+    included do
+      setting :inputs, type: :list do
+        setting :name, type: :string, required: true
+        setting :value, type: :string
+        setting :step, type: :previous_step, label: "Earlier step"
+        setting :output, outputs_of: :step, label: "Earlier step's output"
+      end
+    end
+
+    def self.values_of(node, state)
+      Array(node.config["inputs"]).to_h { |input| [ input["name"], input["step"].present? ? latest_output(input, state) : input["value"] ] }
+    end
+
+    def self.latest_output(input, state)
+      latest_visit = state.keys.select { |key| key.split("@").first == input["step"] }.max_by { |key| key.split("@")[1].to_i }
+      CompletedAt.value_of(state, {}, latest_visit, input["output"])
+    end
+    private_class_method :latest_output
+  end
+end

data/app/models/easy_flow/progress/kept.rb

@@ -5,6 +5,10 @@ module EasyFlow
         @run = run
       end
 
+      def saved?
+        true
+      end
+
       def definition
         @run.pinned_definition
       end

data/app/models/easy_flow/progress/loose.rb

@@ -10,6 +10,10 @@ module EasyFlow
 
       attr_reader :completed_at
 
+      def saved?
+        false
+      end
+
       def definition
         @definition || @flow.live_definition
       end

data/app/models/easy_flow/read_data.rb

@@ -0,0 +1,11 @@
+module EasyFlow
+  class ReadData
+    include Step
+
+    step_name "Read data"
+
+    setting :data, type: :select, label: "What to read", required: true, options: -> { EasyFlow.data_source&.reads.to_a }
+
+    include DataStep
+  end
+end

data/app/models/easy_flow/runner.rb

@@ -29,13 +29,17 @@ module EasyFlow
     end
 
     def run(progress)
-      while (node = @digest.next_step(named(progress.recorded), named(progress.completed_at))) && goes_on?(node, named(progress.recorded), CompletedAt.latest(named(progress.completed_at)))
+      while (node = @digest.next_step(named(progress.recorded), named(progress.completed_at))) && goes_on?(node, named(progress.recorded), CompletedAt.latest(named(progress.completed_at))) && (progress.saved? || refusal_of(node).nil?)
         progress.record(node.id, result_of(@digest.step(node.id), named(progress.recorded)))
       end
       progress.start_inner(node) if node && starts_a_flow?(node)
       progress.ended unless node
     end
 
+    def unsaved_refusal(state, times: {})
+      refusal_of(@digest.next_step(named(state), named(times)))
+    end
+
     def fills_in_next?(state)
       node = @digest.next_step(named(state))
       node.present? && decided?(node, state)
@@ -59,6 +63,10 @@ module EasyFlow
 
     private
 
+    def refusal_of(node)
+      @registry.fetch(node.type).unsaved_refusal if node && @registry.registered?(node.type)
+    end
+
     def starts_a_flow?(node)
       @registry.registered?(node.type) && @registry.fetch(node.type).starts_a_flow?
     end

data/app/models/easy_flow/step_type/declaration.rb

@@ -59,6 +59,10 @@ module EasyFlow
         @answer_labelling = labelling
       end
 
+      def needs_a_saved_run(refusal)
+        @unsaved_refusal = refusal
+      end
+
       def comes_back_while(&return_rule)
         @return_rule = return_rule
       end
@@ -151,7 +155,7 @@ module EasyFlow
         StepType.new(id: @id, step_name: @step_name, settings: settings, awaits_input: @awaits_input,
           ends_here: @ends_here, begins_here: @begins_here, starts_a_flow: @starts_a_flow, plays_the_picked_flow: @plays_the_picked_flow, flow_chooser: @flow_chooser, run_chooser: @run_chooser, behaviour: @behaviour, routing: @routing,
           display: @display, drawn_by: @drawn_by, naming_field: @naming_field, naming: @naming,
-          outputs: @declared_outputs, outputs_named_by: @outputs_named_by, answer_check: @answer_check, answer_labelling: @answer_labelling, readiness: @readiness, return_rule: @return_rule)
+          outputs: @declared_outputs, outputs_named_by: @outputs_named_by, answer_check: @answer_check, answer_labelling: @answer_labelling, readiness: @readiness, return_rule: @return_rule, unsaved_refusal: @unsaved_refusal)
       end
 
       def settings

data/app/models/easy_flow/step_type.rb

@@ -4,11 +4,11 @@ module EasyFlow
       Declaration.new(id).tap { |decl| decl.instance_eval(&declaration) }.to_step_type
     end
 
-    attr_reader :id, :step_name, :settings, :naming_field, :naming, :outputs, :drawn_by
+    attr_reader :id, :step_name, :settings, :naming_field, :naming, :outputs, :drawn_by, :unsaved_refusal
 
     def initialize(id:, step_name:, settings:, awaits_input:, behaviour:, routing:,
       ends_here: false, begins_here: false, starts_a_flow: false, plays_the_picked_flow: false, flow_chooser: nil, run_chooser: nil, display: nil, drawn_by: nil,
-      naming_field: nil, naming: nil, outputs: [], outputs_named_by: nil, answer_check: nil, answer_labelling: nil, readiness: nil, return_rule: nil)
+      naming_field: nil, naming: nil, outputs: [], outputs_named_by: nil, answer_check: nil, answer_labelling: nil, readiness: nil, return_rule: nil, unsaved_refusal: nil)
       @id = id
       @step_name = step_name
       @settings = settings
@@ -31,6 +31,7 @@ module EasyFlow
       @answer_labelling = answer_labelling
       @readiness = readiness
       @return_rule = return_rule
+      @unsaved_refusal = unsaved_refusal
     end
 
     def display_of(node, run = nil)

data/app/models/easy_flow/unconnected_steps.rb

@@ -0,0 +1,44 @@
+module EasyFlow
+  class UnconnectedSteps
+    def initialize(document, flow: nil, registry: EasyFlow.registry)
+      @document = document
+      @flow = flow
+      @registry = registry
+    end
+
+    def ids
+      @document.unconnected
+    end
+
+    def named
+      ids.map { |id| { "id" => id, "label" => Name.of(@document.node(id), @registry) } }
+    end
+
+    def accepted?(named_steps)
+      Array(named_steps).map(&:to_s).sort == ids.map(&:to_s).sort
+    end
+
+    def objections
+      Validator.new(staying, registry: @registry, flow: @flow).violations + readers
+    end
+
+    private
+
+    def readers
+      staying.nodes.select { |node| entries_naming(node).intersect?(ids) }
+        .map { |node| Violation.new(node: node.id, problem: :reading_an_unconnected_step) }
+    end
+
+    def entries_naming(node)
+      return [] unless @registry.registered?(node.type)
+
+      @registry.fetch(node.type).settings.record_fields.flat_map do |list, holds|
+        Array(node.config[list.to_s]).flat_map { |entry| entry.to_h.values_at(*holds.select { |_name, type| type == :previous_step }.keys.map(&:to_s)) }
+      end
+    end
+
+    def staying
+      @document.without(ids)
+    end
+  end
+end

data/app/models/easy_flow/write_data.rb

@@ -0,0 +1,11 @@
+module EasyFlow
+  class WriteData
+    include Step
+
+    step_name "Write data"
+
+    setting :data, type: :select, label: "What to write", required: true, options: -> { EasyFlow.data_source&.writes.to_a }
+
+    include DataStep
+  end
+end

data/app/views/easy_flow/flows/refused.html.erb

@@ -0,0 +1,3 @@
+<%= ui_page(max_width: :md) do %>
+  <%= ui_alert(message: @unsaved_refusal, type: :error) %>
+<% end %>

data/app/views/easy_flow/manage/flows/show.html.erb

@@ -20,7 +20,11 @@
         <%= ui_button(label: "Back to #{@parent.title.presence || @parent.slug}", href: flow_routes.manage_flow_path(@parent), variant: :secondary) %>
       <% end %>
 
-      <%= ui_button(label: "All flows", href: flow_routes.manage_flows_path, variant: :secondary) %>
+      <% if @back_link %>
+        <%= ui_button(label: @back_link.label, href: @back_link.address, variant: :secondary) %>
+      <% else %>
+        <%= ui_button(label: "All flows", href: flow_routes.manage_flows_path, variant: :secondary) %>
+      <% end %>
     </div>
   </header>
 

data/lib/easy_flow/engine.rb

@@ -29,6 +29,8 @@ module EasyFlow
         EasyFlow::CompareTwoValues.register
         EasyFlow::AllOrAny.register
         EasyFlow::Count.register
+        EasyFlow::ReadData.register
+        EasyFlow::WriteData.register
         EasyFlow::Wait.register
         EasyFlow::FlowStep.register
         EasyFlow::PlayFlows.register

data/lib/easy_flow/host.rb

@@ -1,13 +1,19 @@
 module EasyFlow
   class Host
-    attr_reader :name
-    attr_writer :layout, :admin_layout, :offers, :allowed_answers
-    attr_accessor :admin_authentication_method, :visitor_authorization_method, :refusal_method, :owner_method, :finds_flows_across_owners
+    BackLink = Data.define(:label, :address)
+
+    attr_reader :name, :back_link
+    attr_writer :layout, :admin_layout, :offers, :allowed_answers, :always_show_insert_buttons, :hide_step_type_codes
+    attr_accessor :admin_authentication_method, :visitor_authorization_method, :refusal_method, :owner_method, :finds_flows_across_owners, :publish_note
 
     def initialize(name)
       @name = name.to_s
     end
 
+    def back_link=(link)
+      @back_link = link && BackLink.new(**link)
+    end
+
     def layout
       @layout || "easy_flow/application"
     end
@@ -28,6 +34,14 @@ module EasyFlow
       @allowed_answers&.call(step, answers)
     end
 
+    def always_show_insert_buttons?
+      @always_show_insert_buttons.present?
+    end
+
+    def hide_step_type_codes?
+      @hide_step_type_codes.present?
+    end
+
     def offers?(step_type)
       @offers.nil? || @offers.map(&:to_s).include?(step_type.to_s)
     end

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.32.1"
+  VERSION = "0.34.0"
 end

data/lib/easy_flow.rb

@@ -30,7 +30,7 @@ module EasyFlow
 
   class << self
     attr_writer :base_controller
-    attr_accessor :file_store, :picture_store
+    attr_accessor :file_store, :picture_store, :data_source
 
     def base_controller
       @base_controller || "ActionController::Base"

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 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.
+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 seventeen: 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), Read data and Write data (`:read_data` and `:write_data`, which ask the app to carry out one thing from what it says can be read or written, with named inputs, and follow a `passed` or `failed` connection; `easy_flow-install` sets what the app offers), 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
 
@@ -17,6 +17,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - `EasyFlow.step` — declares and registers a step type in one call from a block of the same words, for a type small enough not to need its own class.
 - `labels_answer_by` — a word in a step type's declaration giving the label a run's recorded answer to a step of that type is shown by, on the completion page and from `EasyFlow::QuestionRunner#choice_label`.
 - `outputs_named_by` — a word in a step type's declaration adding one output for each entry an admin enters in one of the type's list settings, named by that entry, so the admin decides the names of the values the step records.
+- `EasyFlow::Inputs` — a module a step type's class includes, after `EasyFlow::Step`, to declare the list of named inputs an admin fills in, each a fixed value or an output of an earlier step. `EasyFlow::Inputs.values_of(node, state)` returns those values as a hash with string keys, reading a step reached more than once at its latest visit.
 - `host.allowed_answers=` — set on a host to a lambda given a step and the answers recorded so far, returning the answers that step may take in this run: several narrows the answers shown, one is recorded without showing the step, and none records a blank and skips it.
 - `EasyFlow::FlowsController` — the visitor controller; the app subclasses it to serve one host's flows from its own routes and to change what happens at the start, on each step and at the finish.
 - `hosted_by` — class method on a `FlowsController` subclass naming the host whose flows it serves.
@@ -78,7 +79,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    ```
 
    A step whose type is not registered is neither shown nor run as that type.
-4. Ask the developer which hosts' admins should be able to add the type. A registered type is in a host's palette, the step types an admin can add on that host's canvas, only when the host names no list of offered step types or its list includes the type's id. A type that declares `ends_here` is in every host's palette, and a type that declares `begins_here` is in none. When a host that names a list should offer the new type, add the type's id to that host's list through `easy_flow-install`. Leaving a type off a host's list only keeps admins from adding it there, and a step of that type already in one of the host's flows is still drawn and run.
+4. Ask the developer which hosts' admins should be able to add the type. A registered type is in a host's palette, the step types an admin can add on that host's canvas, only when the host names no list of offered step types or its list includes the type's id. A type that declares `ends_here` is in every host's palette, and a type that declares `begins_here` is in none. When a host that names a list should offer the new type, add the type's id to that host's list through `easy_flow-install`. Leaving a type off a host's list only keeps admins from adding it there, and a step of that type already in one of the host's flows is still drawn and run, and still opens with all its settings and can be saved.
 5. Use these words to declare the type. Each is called once at class level (or inside the `EasyFlow.step` block):
    - `step_name "<label>"` — the name admins see on the canvas. Defaults to the id.
    - `setting :name, type:, label:, options:, required:, optional:, limit:, check:, from:, outputs_of:, kept_on:, attribute:` — a field the admin fills in on the canvas. `type` is one of `:string`, `:integer`, `:float`, `:boolean`, `:select`, `:multi_select`, `:previous_step`, `:from_step`, `:list`, `:flow`, or boot raises `EasyFlow::UnknownFieldType`. A `:select` or `:multi_select` must pass `options:`, or boot raises the same error. `options:` is either an array of strings, or a lambda taking no arguments that returns one; the lambda is called each time the canvas is opened and each time an admin saves the step's settings, so the options follow the app's data without a restart (`options: -> { Region.order(:name).pluck(:code) }`). A saved setting whose value is no longer among the options is refused the next time the admin saves that step. When the options come from the app's records, ask the developer which records, which column is stored as the value, and whether the list must differ by account or host, since the lambda is passed nothing and the same list is offered everywhere the type is used. A `:list` must take a block of `setting` calls describing one entry. `:previous_step` lets the admin pick an earlier step, and is required unless declared with `optional: true`. Ask the developer whether a step of the type may be left without that earlier step, and when it may, declare `optional: true` and handle a blank value in the type's code. `outputs_of: :<setting>` offers the outputs of the step chosen in that setting, and `from: :<setting>` offers the values of the output chosen in that setting; either one makes the type `:from_step`. A required setting left blank shows `missing setting: <name>` on the step's card, and saving the flow as a new version and publishing it are refused until the admin fills it in. An `outputs_of:` setting left blank is flagged and refused the same way once the setting it reads names a step, whether or not it is declared `required:`. Inside a `:list` entry, a blank required setting, or a blank `outputs_of:` setting whose step is picked, shows `missing setting: <list> <n> <name>` for the entry at position `n` counting from 1. `optional:` has no effect inside a `:list` entry, where a `:previous_step` is required only when declared `required: true`. `:flow` lets the admin pick one of the flows the admin's list shows on the same host, offered by title, and is stored in `node.config` as that flow's id as a string. A `:flow` setting is not checked on save against the flows offered, so code that reads it looks the flow up through the host and handles a blank or unknown id. `limit:` is the most values a `:multi_select` takes. `check:` is a lambda given the value that returns an error message, or `nil` when the value is acceptable. `label:` defaults to the name humanized. `kept_on:` and `attribute:` keep the setting's value on one of the app's own records instead of in the flow; see "Keep a setting on one of the app's records".
@@ -279,6 +280,31 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
      - The app calls `run.advance` where the event is handled, such as a webhook or a job. See "Read a run and its answers". This needs a stored run, so it only applies to a flow the admin set to save each step.
 9. Restart the server, open a flow on the canvas of each host that should offer the type, and check the type is in the palette, its settings show, and a preview walks through it. On a host that names a list of offered step types without the type's id, check the type is not in the palette. For a type that declares `starts_a_flow`, check the step is marked `Runs a flow`, that once a flow is picked in its settings clicking the step goes to that flow's page, that the `Back to` button on that page returns to the flow the step is in, and that its `Settings` button opens its settings. Also check that the step shows `missing flow` while no flow is picked, `unrunnable version` while the version number names no live or replaced version, `circular` while it names the flow it sits in, and that publishing is refused until each is fixed. For a type that declares `chooses_flow`, set the settings the block reads and check that clicking the step goes to the flow the block names, that a type with no `names_by` is named on the canvas by that flow's title and version, and that a run stopping at the step starts a run of that flow on that version. For a type that declares `chooses_flow_from_run`, start a stored run whose owner or answers the block reads, walk it to the step, and check `run.waiting_on` is a run of the flow and version the block names, and that a run for which the block names no flow raises `EasyFlow::InnerFlowError`.
 
+### Take named inputs at a step type of the app's own
+
+1. Include `EasyFlow::Inputs` after `EasyFlow::Step`, and read the values in `process`:
+
+   ```ruby
+   class FlowSteps::Script
+     include EasyFlow::Step
+     include EasyFlow::Inputs
+
+     step_name "Script"
+
+     def process(node, state)
+       ScriptRunner.call(EasyFlow::Inputs.values_of(node, state))
+     end
+   end
+   ```
+
+2. What then holds:
+   - The step's settings on the canvas hold an `inputs` list, and each entry takes a name, a fixed value, an earlier step and that step's output.
+   - An entry that names an earlier step reads that step's output, at its latest visit when a loop reached it more than once. Any other entry gives its fixed value.
+   - `state` in `process` still holds every visit under its own key, so a step type that adds up every visit keeps working.
+   - An earlier step that recorded a plain value gives that value for whichever output the entry names.
+   - `process` is not given completion times, so an entry naming "Hour completed", "Weekday completed" or "Minutes since 1970 when completed" gives nothing.
+3. Publish a flow set to save each step with a loop back to a question before the step, answer it twice, and check the step reads the second answer.
+
 ### Keep a setting on one of the app's records
 
 Use this when an admin should edit a value that belongs to one of the app's own records, such as a customer's name, from a step's settings on the canvas, and the flow should not hold a copy of it.
@@ -536,7 +562,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`, `multiple_select`, `fill_in_the_blank`, `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`, `read_data`, `write_data`, `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.
@@ -555,6 +581,7 @@ Use this when a visitor's run should stop until a set time has passed, such as a
 - A flow holding a `starts_a_flow` step whose `flow` names no existing flow, or whose `version` names no live or replaced version of it, or whose `flow` leads back to the flow the step sits in directly or through other flows, cannot be saved as a version or published, and these checks cannot be turned off.
 - On the canvas, clicking a step of a `starts_a_flow` type whose `flow` setting names a flow goes to that flow's page, which has a `Back to` button to the flow the step is in, and the step's settings open from its `Settings` button.
 - A `:previous_step` setting is required unless declared `optional: true`, and an `outputs_of:` setting must be filled once the step it reads is picked, or the flow cannot be saved as a version or published.
+- Only the canvas's Create version and Publish requests remove unconnected steps, and only when the request's `remove_unconnected` names exactly the steps unconnected at that moment. `Definition#publish`, `Definition#create_version` and `Validator#violations` never remove one, and `violations` lists each as `unreachable`, so app code that checks `violations` before publishing goes on refusing such a flow. A request that names none is answered with status 422, the refusal in `error`, and the steps in `unconnected`.
 - A type that routes declares the values its output takes, or the canvas offers no connections to label.
 - An output named by `outputs_named_by` takes its name from an entry's `name`, lists no values, and is never a connection leaving the step.
 - A run starts only on a version its own flow has published and not retired or withdrawn, and any other version raises `ActiveRecord::RecordInvalid`.

data/the_local/agents/easy_flow-info.md

@@ -31,6 +31,7 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - To branch a flow on several comparisons at once, such as whether a reading is above one amount and a second reading is below another, no code is needed: an admin places an All of or Any of step on the canvas and lists the comparisons.
 - To branch a flow on when a step was completed, such as the hour of the day or the weekday, or on how many minutes passed between two steps being completed, no code is needed: an admin places a Compare or Compare two values step on the canvas and picks one of the completion time outputs.
 - To hold a run for a number of minutes after a step was completed, until the next time of day after it, or until a date, no code is needed: an admin places a Wait step on the canvas.
+- To read from or write to the app inside a flow, no step type is needed: the app says what can be read and written and how, and an admin places a Read data or Write data step on the canvas.
 - To make a visitor answer a question or tick something on a checklist before going on, no code is needed: an admin marks that step as required on the canvas.
 - To let a visitor tick several answers on one step, no code is needed: an admin places a checklist step on the canvas.
 - To explain an answer to the visitor, no code is needed: an admin fills in that answer's info on a question or checklist step.
@@ -44,6 +45,7 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Flow** — one guided path, found by its slug within its host. It holds a working document the admin edits and a list of versions.
 - **Document** — the flow's content: its steps (nodes), the connections between them (edges), a headline and a slug.
 - **Version** — a numbered snapshot of the document. A version is a draft until it is published, and a flow has at most one live version at a time. Publishing another version makes the one that was live superseded. A version can also be retired or withdrawn, and a retired or withdrawn version cannot be published again.
+- **Unconnected step** — a step on the canvas the flow does not reach from its start, left to the side until an admin connects it. It stays in the working document through every edit. Create version and Publish warn with each such step's name, and only an admin accepting that warning removes them. Accepting saves a draft version with the steps in it first, which an admin can return to from the history, then creates or publishes the next version without them. A second start step is not counted, and a problem on a step that stays still blocks.
 - **Published version** — a version that is live or superseded, which is any version that has been published and not taken out of service.
 - **Removing a flow** — an admin deleting a flow from the admin's list of flows. It deletes the flow's versions and its runs with it. A run of another flow that one of those runs had started is kept, and no longer records a run that started it. A flow is not removed while a run of it is the inner run that a run of another flow is stopped at a Flow step waiting on. The admin is then told "This flow cannot be removed while" followed by the waiting flow's title, or its slug when it has no title, and "waits on one of its runs".
 - **Canvas** — the admin screen where steps are added, configured, moved, removed and connected, with undo and redo. Publishing happens there.
@@ -74,6 +76,8 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Compare** — a built-in branching step that reads an earlier step's answer as a number and checks it against an amount by more than, less than, at least or at most, then follows the true or the false connection. The admin picks which of the earlier step's outputs to read, as described under chosen output. An answer that is missing or is not a number decides false.
 - **Compare two values** — a built-in branching step that reads two earlier steps' answers as numbers and checks the first against the second by more than, less than, at least, at most or equal to, then follows the true or the false connection. For each side the admin picks which of that step's outputs to read, as described under chosen output. An optional amount is added to the second answer before the check, so "more than" with an amount of 5 is true only when the first answer exceeds the second by more than 5, and a blank amount adds nothing. The second step may be left empty, and the first answer is then checked against the amount alone, or against 0 when the amount is blank too. When either answer is missing or is not a number, the step decides false.
 - **All of or Any of** — a built-in branching step that holds a list of comparisons and a "Must hold" setting of "all of" or "any of", then follows the true or the false connection. Each comparison names an earlier step and which of its outputs to read, then more than, less than, at least, at most or equal to, then an amount, a second step with its output, or both. A comparison with a second step holds the same way a Compare two values step would decide, adding the amount to the second answer, and one with no second step checks the first answer against the amount alone. "All of" decides true only when every comparison holds, and "any of" when at least one does. A comparison whose answer is missing or is not a number does not hold, and a step with no comparisons decides false.
+- **Read data and Write data** — built-in steps that ask the app to carry out one thing from its list of what a flow can read or write, in a nested transaction, then follow the `passed` or the `failed` connection. The step records `result`, `reason` on a failure, and the app's answer: a hash as named outputs, anything else as `answer`. The admin lists the answer's names under "Values it reports" so later steps can pick them. Both need a flow that keeps every answer as it is given. In a flow that keeps nothing or keeps the run only once it finishes, the visitor is told "Data can only be read or written in a flow that saves its runs." when the run reaches the step and cannot go on, and the app is not called.
+- **Input** — a named value a Read data or Write data step passes to the app, either a fixed value or an output of an earlier step. A step reached more than once gives its most recent output.
 - **Completion time** — the time a step was completed, kept for every visit beside the value that visit recorded. Every step that records a value has one, including steps that act on their own and waiting steps, not only steps a visitor answers. A stored run saves it with the run. A flow that carries its answers in the page carries each completion time in the page too, gives a value sent without a time the time it arrived, and drops a time it cannot read. A run stored when such a flow finishes keeps the completion times of the visits on its path. Going back discards the last visit's completion time with its value.
 - **Completion time outputs** — three outputs every step that records a value offers beside its own: "Hour completed", the hour from 0 to 23 in the app's time zone, "Weekday completed", from 1 for Monday to 7 for Sunday, and "Minutes since 1970 when completed", the whole minutes since the start of 1 January 1970 in UTC. Each is read from the completion time of the latest visit to that step, and a step with no completion time has none of them. Compare, Compare two values and All of or Any of read them, so Compare two values with "more than" and an amount of 30 on two steps' minutes is true when the first step was completed more than 30 minutes after the second. Condition and Count list them among a step's outputs but do not read the time when one is picked.
 - **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.
@@ -93,7 +97,13 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Host** — a named part of the app that owns a set of flows. A host sets the visitor layout and the admin layout, how admins are authenticated, how visitors are authorized, how a refusal is answered, and optionally which step types it offers and which answers it allows a step in a run. Flows are always looked up through a host, so one host never sees another's flows.
 - **Offered step types** — the list of step types a host names for its admins to add. A host that names no list offers every registered step type. The list only narrows the palette.
 - **Allowed answers** — a rule a host may carry that looks at a step and the answers given so far in a run and names the answer values that step allows. When it names nothing for a step, the step offers every answer. When it names several, a question or checklist offers only those. When it names exactly one, the step records that answer without being shown, and when it names none, the step is passed over and records a blank answer. This holds in a stored run, a run moved on outside a visitor's request, a flow that carries its answers in the page, and an admin's preview. Going back skips the steps the host filled in and returns to the last step the visitor was shown.
-- **Palette** — the step types an admin can add on a host's canvas. It never holds the start step, always holds the end step, and otherwise holds the step types the host offers. A step already in a flow whose type the host does not offer is still drawn and run.
+- **Always-visible insert buttons** — a setting a host may turn on, `always_show_insert_buttons`, that shows each connection's button for inserting a step on its canvas without the pointer over the connection, with the connection's label moved to the right of the line. It is off by default, and with it off the button shows only with the pointer over the connection.
+- **Hidden step type codes** — a setting a host may turn on, `hide_step_type_codes`, that hides step type code names on its canvas. The add menu lists each step type by its name alone, and a step's box shows its step type's name in place of the code name, with a step that has no name of its own headed by its step type's name. It is off by default, and with it off the add menu and step boxes show the code names. The settings panel shows a step's id and code name either way.
+- **Publish note** — a setting a host may set, `publish_note`, whose sentence is shown directly under the Publish button in its flow panel. With none set, the panel shows no note.
+- **Back link** — a setting a host may set, `back_link`, holding a label and an address, that shows a button with that label and address in its builder header in place of `All flows`. With none set, the header shows `All flows`.
+- **Flow panel** — the panel the `This flow` button opens on the canvas, on every host. It shows Create version and Publish above its lists of problems and changes. Several saves to the same step in a row show as one line in the changes list, named by the step's latest name. A save, a move and any other change each keep their own line, and the history of versions still lists every change a version captured.
+- **Picture mark** — the words `Has a picture` on the box of a step with a picture on the canvas, on every host.
+- **Palette** — the step types an admin can add on a host's canvas. It never holds the start step, always holds the end step, and otherwise holds the step types the host offers. A step already in a flow whose type the host does not offer is still drawn and run, and still opens with all its settings and can be saved.
 - **Run** — one visitor's pass through a flow. A run may belong to one of the app's own records, its owner, which the app sets. A run is pinned to the version it started on, so publishing a new version does not change a run already under way. A run starts on the live version unless the app chooses another of the flow's published versions. A run is refused when the chosen version is a draft, is retired or withdrawn, or belongs to another flow. It records each visit, and going back discards the last visit on the path.
 - **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.