easy_flow 0.4.7 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92d52fb553f82cf1f206f0257d5d4fdaa0718ec6197ccabf016e6b20107371da
-  data.tar.gz: 66a5f5930c064d692b3c8b410174119e697c97b6a9ec47e8e9bffccd7abf7f5c
+  metadata.gz: 0f7ac7fa5bfb54fd32b37779b0ec07dcaf754d8d242fedac33fffa58e1c49d22
+  data.tar.gz: 9947469ec0272eccb7624372e102e6b60f9a93ebbe08572846246f8ae956eb56
 SHA512:
-  metadata.gz: a982c31c2a100d8f74b6d75346200f68c1aad256e2ff87b24267fc509fca46ef19da19fb169f48798d4f33cf44d6dee011164f2a7df3dc4107b9b1cdbe081b43
-  data.tar.gz: 97ee4e459a2c25a0ef77b5433e056cfa83ccc40a9b0cf73abad201b9fcec9d5ea6e8079396d6d7ad4ed3ec904d7035c103b9ba045fd81d394096c339903cda80
+  metadata.gz: 2ec1059bd29bcd076aef6df9a4f713690ebd7e8bb786e1c05bf51d9991b23f497c3e83bfb4aad12063168b9d5fdf96f4a265dbe1cb496a7fbe5a4238053db9aa
+  data.tar.gz: ea9a2e1eabb38ccad3426bb487f8a9e1933eb83e4c4d98920868e926e5f963d7eefd4aeed3604663f2c1b47e5651c84f458a19a5fe2abd044d664fd755634ef4

data/app/controllers/easy_flow/flows_controller.rb

@@ -18,6 +18,7 @@ module EasyFlow
       @question = @guide.next_step(@answers)
       @drawing = @guide.drawing_at(@answers)
       flash.now[:alert] = @refused if @refused
+      @waiting = waiting_on(@question)
       return render :step if @question
 
       render_completion
@@ -124,6 +125,13 @@ module EasyFlow
       progress.record(id, value.to_s)
     end
 
+    def waiting_on(step)
+      return unless step.respond_to?(:type) && EasyFlow.registry.registered?(step.type)
+
+      step_type = EasyFlow.registry.fetch(step.type)
+      step_type.name_of(step).presence || step_type.step_name if step_type.waits?
+    end
+
     def answer_problem(step, answer)
       return unless step && EasyFlow.registry.registered?(step.type)
 

data/app/models/easy_flow/digest.rb

@@ -92,7 +92,7 @@ module EasyFlow
     def pending?(node, state)
       return false if state.key?(node.id)
 
-      step_type(node)&.awaits_input? || acts?(node)
+      step_type(node)&.awaits_input? || acts?(node) || step_type(node)&.waits? || false
     end
 
     def acts?(node)

data/app/models/easy_flow/run.rb

@@ -18,6 +18,10 @@ module EasyFlow
       super.to_h.symbolize_keys
     end
 
+    def advance
+      Runner.new(pinned_definition).run(Progress::Kept.new(self))
+    end
+
     def pinned_definition
       definition_version.definition.to_h
     end

data/app/models/easy_flow/runner.rb

@@ -27,8 +27,8 @@ module EasyFlow
     end
 
     def run(progress)
-      while (node = @digest.next_step(named(progress.recorded))) && acts?(node)
-        progress.record(node.id, @registry.fetch(node.type).process(node, named(progress.recorded)))
+      while (node = @digest.next_step(named(progress.recorded))) && goes_on?(node, named(progress.recorded))
+        progress.record(node.id, result_of(node, named(progress.recorded)))
       end
     end
 
@@ -50,6 +50,18 @@ module EasyFlow
       @registry.registered?(node.type) && @registry.fetch(node.type).acts?
     end
 
+    def goes_on?(node, state)
+      acts?(node) || ready?(node, state)
+    end
+
+    def ready?(node, state)
+      @registry.registered?(node.type) && @registry.fetch(node.type).waits? && @registry.fetch(node.type).ready?(node, state)
+    end
+
+    def result_of(node, state)
+      acts?(node) ? @registry.fetch(node.type).process(node, state) : true
+    end
+
     def shown(node)
       return node unless node && @registry.registered?(node.type)
 

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

@@ -44,6 +44,10 @@ module EasyFlow
         @answer_check = check
       end
 
+      def waits_until(&readiness)
+        @readiness = readiness
+      end
+
       def step_name(value)
         @step_name = value
       end
@@ -107,7 +111,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, behaviour: @behaviour, routing: @routing,
           display: @display, drawn_by: @drawn_by, naming_field: @naming_field, naming: @naming,
-          outputs: @declared_outputs, answer_check: @answer_check)
+          outputs: @declared_outputs, answer_check: @answer_check, readiness: @readiness)
       end
 
       def settings

data/app/models/easy_flow/step_type.rb

@@ -8,7 +8,7 @@ module EasyFlow
 
     def initialize(id:, step_name:, settings:, awaits_input:, behaviour:, routing:,
       ends_here: false, begins_here: false, display: nil, drawn_by: nil,
-      naming_field: nil, naming: nil, outputs: [], answer_check: nil)
+      naming_field: nil, naming: nil, outputs: [], answer_check: nil, readiness: nil)
       @id = id
       @step_name = step_name
       @settings = settings
@@ -23,6 +23,7 @@ module EasyFlow
       @naming = naming
       @outputs = outputs
       @answer_check = answer_check
+      @readiness = readiness
     end
 
     def display_of(node)
@@ -41,6 +42,14 @@ module EasyFlow
       @answer_check&.call(node, value)
     end
 
+    def waits?
+      @readiness.present?
+    end
+
+    def ready?(node, state)
+      @readiness.call(node, state)
+    end
+
     def name_of(node)
       @naming&.call(node).presence || node.config[naming_field.to_s].presence
     end

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

@@ -11,22 +11,26 @@
     <div class="mb-6"><%= ui_alert(message: flash[:alert], type: :error) %></div>
   <% end %>
 
-  <%= form_with url: step_form[:url], method: step_form[:method], data: { turbo: false } do %>
-    <%= hidden_field_tag :asked, @question.id %>
-    <% if carries_answers? %>
-      <% @answers.each do |key, value| %>
-        <%= hidden_field_tag "answers[#{key}]", value %>
+  <% if @waiting %>
+    <p class="text-gray-700">Waiting for <%= @waiting %>.</p>
+  <% else %>
+    <%= form_with url: step_form[:url], method: step_form[:method], data: { turbo: false } do %>
+      <%= hidden_field_tag :asked, @question.id %>
+      <% if carries_answers? %>
+        <% @answers.each do |key, value| %>
+          <%= hidden_field_tag "answers[#{key}]", value %>
+        <% end %>
       <% end %>
-    <% end %>
 
-    <%= render @drawing, step: @question %>
+      <%= render @drawing, step: @question %>
 
-    <div class="mt-8 flex items-center gap-4">
-      <%= ui_button(label: "Next", type: :submit) %>
+      <div class="mt-8 flex items-center gap-4">
+        <%= ui_button(label: "Next", type: :submit) %>
 
-      <% if @answers.any? %>
-        <button type="submit" name="back" value="1" formnovalidate class="cursor-pointer text-sm text-gray-500 underline underline-offset-2 hover:text-gray-900">← Back</button>
-      <% end %>
-    </div>
+        <% if @answers.any? %>
+          <button type="submit" name="back" value="1" formnovalidate class="cursor-pointer text-sm text-gray-500 underline underline-offset-2 hover:text-gray-900">← Back</button>
+        <% end %>
+      </div>
+    <% end %>
   <% end %>
 <% end %>

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.4.7"
+  VERSION = "0.4.8"
 end

data/the_local/agents/easy_flow-develop.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-develop
-description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, computes a value from earlier answers, or picks the next branch), refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, serving a host's flows from the app's own controller and routes, acting when a visitor finishes a flow, and reading a run's recorded answers and question labels — MUST BE USED instead of hand-rolling questionnaire steps, branching logic, number comparisons, hard-coded setting options, answer validation, flow controllers or answer lookups.
+description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, computes a value from earlier answers, picks the next branch, or holds the visitor until something outside the flow has happened), moving a paused run on once what it waits for has happened, refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, serving a host's flows from the app's own controller and routes, acting when a visitor finishes a flow, and reading a run's recorded answers and question labels — MUST BE USED instead of hand-rolling questionnaire steps, branching logic, number comparisons, hard-coded setting options, answer validation, polling or "come back later" pages, flow controllers or answer lookups.
 tools: Read, Write, Edit, Grep
 scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
 ---
@@ -18,7 +18,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - `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.
 - `routed_by` — class method on a `FlowsController` subclass naming the prefix of the app's own route names that the controller redirects and links to.
-- `EasyFlow::Run` — the stored record of one visitor's pass through a flow, pinned to the version that was live when it started.
+- `EasyFlow::Run` — the stored record of one visitor's pass through a flow, pinned to the version that was live when it started, and moved on past a waiting step with `advance`.
 - `EasyFlow::QuestionRunner` — reads a flow document: its steps, the next step for a set of answers, the answers on the path taken, and a question's text and an answer's label.
 
 ## How to use it
@@ -29,7 +29,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - It asks the visitor for input — declare `awaits_input`.
    - It computes a value from earlier answers with no visitor input — define `process`.
    - It only picks which connection to follow — define `route`.
-   A type may both `process` and `route`. A type that does none of the three is passed through without stopping when a visitor reaches it.
+   - It holds the visitor until something outside the flow has happened, such as a payment arriving or a reviewer approving — declare `waits_until`.
+   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`, `condition`, `switch` or `compare`:
 
    ```ruby
@@ -78,6 +79,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `output :name, type:, label:, values:, from:` — a value the step records. `type` is one of `:string`, `:integer`, `:float`, `:boolean`, or boot raises `EasyFlow::UnknownOutputType`. `values:` is an array or a lambda taking the node, listing the values the output can take; the canvas offers these as the connections leaving the step, so a type that routes must declare them. `from: :<setting>` takes the values from the step chosen in that setting.
    - `names_by :setting` or `names_by { |node| ... }` — what the step is called on the canvas, from a setting or computed.
    - `awaits_input` — the visitor is shown this step and submits an answer to it.
+   - `waits_until { |node, state| ... }` — the run stops at this step until the block returns a truthy value. See step 7.
    - `answer_check { |node, value| ... }` — checks a submitted answer before it is recorded. `value` is the submitted string, or `nil` when the input sent nothing. Return a message to refuse the answer, or `nil` to accept it. Without it every answer is accepted, including a blank one.
    - `ends_here` / `begins_here` — marks the type as an end or a start of a flow.
    - `displays_by { |node| ... }` — builds the object handed to the step's partial as the local `step`. Without it the partial receives the node itself.
@@ -116,7 +118,31 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    setting :required, type: :boolean
    answer_check { |node, value| "Fill this in to go on." if node.config["required"] && value.blank? }
    ```
-7. Restart the server, open a flow on the canvas and check the type is offered, its settings show, and a preview walks through it.
+7. For a type that waits, declare `waits_until` with a block that says whether what the step waits for has happened:
+
+   ```ruby
+   module FlowSteps
+     class AwaitPayment
+       include EasyFlow::Step
+
+       step_name "Payment"
+
+       setting :invoice_step, type: :previous_step
+
+       waits_until { |node, state| Invoice.paid?(state[node.config["invoice_step"]]) }
+     end
+   end
+   ```
+
+   - The block is given `node` and `state` only, the same as `process`, and is not given the run or its owner. Ask the developer what the step waits for, and how the block finds it from the step's settings and the answers recorded before it. If it cannot be found from those, stop and ask, since the block has nothing else to read.
+   - The block is called each time the visitor loads the step page, and each time the app calls `run.advance`. Keep it to a single lookup.
+   - While the block returns a falsy value, the visitor is shown `Waiting for <name>.` and no form, no Next button and no Back button. `<name>` is what `names_by` gives, or the `step_name` when there is none, so give the type a name a visitor can read.
+   - Once the block returns a truthy value, `true` is recorded under the step's id, or the value `process` returns when the type also defines `process`, and the run goes on to the next step.
+   - Do not declare `awaits_input` on a type that waits. The waiting message replaces the form, so the input is never shown.
+   - The page does not reload itself. Ask the developer how the run should move on when what it waits for happens:
+     - The visitor reloads the page. This needs nothing more, and works whether or not the flow keeps a stored run.
+     - 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.
+8. Restart the server, open a flow on the canvas and check the type is offered, its settings show, and a preview walks through it.
 
 ### Serve a host's flows from the app's own controller
 
@@ -162,6 +188,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `run.owner` — the optional record the run belongs to, polymorphic, set by the app. `run.label` and `run.status` are free string columns for the app's own use.
    - `run.pinned_definition` — the flow document of the version the run started on.
    - `run.next_step(answers)` and `run.walked(answers)` — the next step, and the answers on the path taken, for a set of answers against that pinned version.
+   - `run.advance` — moves the run past every waiting step whose `waits_until` block now returns a truthy value, and past every step that computes a value, and records each result on the run. It stops at the next step that asks the visitor for input, the next waiting step that is not ready, or the end. It does not call `finished`; that is called the next time the visitor loads the run's page.
 3. To show answers with their question text and answer labels, build a runner from the run's pinned document:
 
    ```ruby
@@ -187,5 +214,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - Always look flows and runs up through a host.
 - A step's input field is named `answers[<step id>]` and submits one value. Any other name is ignored, and an array or hash is treated as blank.
 - An answer the type's `answer_check` refuses is never recorded, and the visitor is shown the same step with the check's message. An answer no check refuses is recorded, a blank one as `""`.
+- A `waits_until` block is given only the step and the answers recorded so far, so what it waits for must be findable from those.
+- A type that waits never also declares `awaits_input`.
+- `run.advance` only moves a stored run, and never finishes it; the visitor's next page load does.
 - A `FlowsController` subclass needs all four named routes for its prefix; a missing one raises when the visitor is linked or redirected to it.
 - The engine installs, mounts and configures hosts, layouts, the default drawing and checks through `easy_flow-install`, not here.

data/the_local/agents/easy_flow-info.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-info
-description: Use to learn what easy_flow offers — guided flows an admin draws on a canvas and a visitor runs one step at a time, versioned documents of steps and connections, hosts, runs, the built-in step types including questions that can require an answer and branching on an answer or comparing a number, step types the host app registers and the checks they make on an answer, and the settings an admin fills in, including picks whose options come from the app's data.
+description: Use to learn what easy_flow offers — guided flows an admin draws on a canvas and a visitor runs one step at a time, versioned documents of steps and connections, hosts, runs, the built-in step types including questions that can require an answer and branching on an answer or comparing a number, step types the host app registers, the checks they make on an answer, and steps that hold a run until something outside the flow has happened, and the settings an admin fills in, including picks whose options come from the app's data.
 tools: Read
 scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
 ---
@@ -11,19 +11,19 @@ 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, and three steps that pick a branch from earlier answers. Anything else a flow needs to ask or do 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, and three steps that pick a branch from earlier answers. Anything else a flow needs to ask, do, or wait for is a step type the app declares itself.
 
 ## Interface
 
 easy_flow declares no commands of its own for this local. Its surface is split between the other two:
 
 - **easy_flow-install** owns putting the engine into an app: its migrations, mounting it, choosing the controller it inherits from, naming hosts, choosing the default step drawing, the flow checks, and the admin pages.
-- **easy_flow-develop** owns building on it: declaring and registering step types, serving a host's flows from the app's own controllers and routes, and reading a visitor's run and answers.
+- **easy_flow-develop** owns building on it: declaring and registering step types, including ones that wait, moving a run on once what it waits for has happened, serving a host's flows from the app's own controllers and routes, and reading a visitor's run and answers.
 
 ## How to use it
 
 - To get easy_flow running in an app, or to change how it is configured, use **easy_flow-install**.
-- To add a step type, give a step type its own rule for refusing an answer, put a flow on the app's own pages, or act on what a visitor answered, use **easy_flow-develop**.
+- To add a step type, give a step type its own rule for refusing an answer, hold a run until something outside the flow has happened, put a flow on the app's own pages, or act on what a visitor answered, use **easy_flow-develop**.
 - To branch a flow on an answer or on a number the visitor gave, no code is needed: an admin places one of the built-in branching steps on the canvas.
 - To make a visitor answer a question before going on, no code is needed: an admin marks that question step as required on the canvas.
 - If the question is only what a word below means, this page is the answer.
@@ -35,7 +35,7 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **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.
 - **Canvas** — the admin screen where steps are added, configured, moved, removed and connected, with undo and redo. Publishing happens there.
 - **Preview** — an admin walking the current flow without starting a stored run.
-- **Step type** — what a kind of step is: its display name, its settings (the fields an admin fills in), its outputs (the values it records), and whether it waits for the visitor or acts on its own. A step that acts on its own may record a value worked out from the answers so far, pick which connection to follow, or both.
+- **Step type** — what a kind of step is: its display name, its settings (the fields an admin fills in), its outputs (the values it records), and whether it waits for the visitor, acts on its own, or waits for something outside the flow. A step that acts on its own may record a value worked out from the answers so far, pick which connection to follow, or both.
 - **Answer check** — a rule a step type may carry that looks at a visitor's answer and, when the answer is not acceptable, returns the message the visitor sees. A step type with no such rule accepts every answer.
 - **Setting** — one field an admin fills in when configuring a step on the canvas. It is text, a whole number, a decimal, a yes or no, a pick from a list, several picks from a list, an earlier step, an earlier step's output, or a list of entries that each hold their own fields. A setting can be required, limited to a number of picks, or checked by a rule the step type supplies.
 - **Options** — the values a pick-from-a-list setting offers. They are either a fixed list written into the step type, or a lookup the app provides that is read each time the canvas or a save asks for them, so they can come from the app's own data. A saved value that is not among the options is refused.
@@ -46,6 +46,7 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Condition** — a built-in branching step that checks whether an earlier step's answer is, or is not, a chosen value, and follows the true or the false connection.
 - **Switch** — a built-in branching step that follows the connection labelled with an earlier step's answer.
 - **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. When the earlier step recorded several outputs, the admin picks which one. An answer that is missing or is not a number decides false.
+- **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`.
 - **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.
 - **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, and how a refusal is answered. Flows are always looked up through a host, so one host never sees another's flows.
 - **Run** — one visitor's pass through a flow. A run is pinned to the version that was live when it started, so publishing a new version does not change a run already under way. It records each answer by step id, and going back discards the last answer on the path.

data/the_local/agents/easy_flow-install.md

@@ -60,7 +60,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    ```
 
    A mount whose host name is not declared serves no flows, and its admin pages return `404 Not Found`.
-8. Ask the developer whether visitors' steps should be drawn with the engine's own partial or with one from the app. For the app's own, create a partial, for example `app/views/steps/_step.html.erb`, which receives the step as the local `step`. Then add to the initializer:
+8. Ask the developer whether visitors' steps should be drawn with the engine's own partial or with one from the app. For the app's own, create a partial, for example `app/views/steps/_step.html.erb`, which receives the step as the local `step`. It is rendered inside the engine's form, so it draws only the fields, and the visitor's answer must be submitted as `answers[<%= step.id %>]`. Then add to the initializer:
 
    ```ruby
    EasyFlow.draws_with("steps/step")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_flow
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 0.4.8
 platform: ruby
 authors:
 - tylercschneider