easy_flow 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d14521622c3830ea4e9608d08eaa8b8d90125cd898bdf8aa8547b09a80aa905
-  data.tar.gz: cd223813e0562b015871a7b614fc9ae343a954fd52ec44b06e2197fd6f758297
+  metadata.gz: 9ac79c8ce4bb5e4684bffa9ae4e01b03d7eedfc7bcea71d942a42001fdbd1b3e
+  data.tar.gz: 36dcb39f97780d9132bcd71a5a7dd3a335859d88ce0623dd4610ed1882e2b1e9
 SHA512:
-  metadata.gz: e2b3b92295289c74be0bbde30055366b5c9d59c07378bda7347d723c4e8dc6a74a5fb15681cde91345f35ed17816e46995ceb2f9bc323221e5b7655a0efe320b
-  data.tar.gz: 3f8e757df44027f931efd503d54f1640a486e6cd9b2f56825f4c95b9036d2653731d5318b28ac16de701b93e0861b1bc41d07c4ca9c8192a00cc5cca24e3aad8
+  metadata.gz: a07323057c7278472b1233247d518ccee87aa7baf27ec5e53f1b747345b3c7909c3be28fde2fbaf43871655627efc163461d3aa683fa2548dc27b4f8bb322670
+  data.tar.gz: db782393e3af4feef0e360158d4702fb250c3d3251046e65ebe03256a153e23a649814cef0cb7d0db5591d1ba14cef841a41837b98069a92378d8eaaa2a43754

data/app/models/easy_flow/compare.rb

@@ -0,0 +1,25 @@
+module EasyFlow
+  class Compare
+    include Step
+
+    COMPARISONS = { "more than" => :>, "less than" => :<, "at least" => :>=, "at most" => :<= }.freeze
+
+    step_name "Compare"
+
+    setting :step, type: :previous_step
+    setting :output, outputs_of: :step
+    setting :comparison, type: :select, options: COMPARISONS.keys, required: true
+    setting :amount, type: :float, required: true
+
+    output :result, type: :boolean, values: [ true, false ]
+
+    def route(node, state)
+      answer = state[node.config["step"]]
+      answer = answer[node.config["output"]] if answer.is_a?(Hash)
+      number = Float(answer.to_s, exception: false)
+      return false if number.nil?
+
+      number.public_send(COMPARISONS.fetch(node.config["comparison"]), node.config["amount"])
+    end
+  end
+end

data/lib/easy_flow/engine.rb

@@ -21,6 +21,7 @@ module EasyFlow
         EasyFlow::Steps::Question.register
         EasyFlow::Condition.register
         EasyFlow::Switch.register
+        EasyFlow::Compare.register
 
         EasyFlow.check(:unrouted_value)
         EasyFlow.check(:unfollowed_path)

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.4.4"
+  VERSION = "0.4.5"
 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), 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, 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, or picks the next branch), 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, 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
 ---
@@ -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, and the engine ships the question type (a question with a list of answers) plus its own start, end, condition and switch types. 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, 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 six: start (`:start`), end (`:terminal`), question (`:question`, a question with a list of answers), and three that pick a branch from an earlier answer with no code — condition (`:condition`, is or is not a chosen value), switch (`:switch`, follows the connection labelled with the answer) and compare (`:compare`, reads the answer as a number and checks it by more than, less than, at least or at most against an amount). Before writing a step type to branch on an answer or a number, ask the developer whether an admin placing one of those three on the canvas is enough. 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, 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
 
@@ -29,8 +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 skipped 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:
+   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.
+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
    module FlowSteps
@@ -74,8 +74,8 @@ 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. 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:, limit:, check:, from:, outputs_of:` — 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`. A `:select` or `:multi_select` must pass `options:`, or boot raises `EasyFlow::UnknownFieldType`. A `:list` must take a block of `setting` calls describing one entry. `:previous_step` lets the admin pick an earlier step. `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`.
-   - `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. `from: :<setting>` takes the values from the step chosen in that setting.
+   - `setting :name, type:, label:, options:, required:, limit:, check:, from:, outputs_of:` — 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`, or boot raises `EasyFlow::UnknownFieldType`. A `:select` or `:multi_select` must pass `options:`, or boot raises the same error. A `:list` must take a block of `setting` calls describing one entry. `:previous_step` lets the admin pick an earlier step, and is always required. `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`. `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.
+   - `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 must answer it.
    - `ends_here` / `begins_here` — marks the type as an end or a start of a flow.
@@ -96,7 +96,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `node` has `id`, `type` and `config`; `config` is a hash of the admin's settings with string keys.
    - `state` is the answers recorded so far, keyed by step id as strings.
    - `process` returns the value recorded under this step's id. It runs as soon as a visitor reaches the step, before the next step is shown.
-   - `route` returns the value that picks the connection to follow; it is compared as a string with the value each leaving connection is labelled with. Returning `nil` follows the first connection.
+   - A type that declares more than one `output` returns a hash from `process`, keyed by each output's name as a string. A later compare step reads the output the admin picks from that hash.
+   - `route` returns the value that picks the connection to follow; it is compared as a string with the value each leaving connection is labelled with, so `false` follows the connection labelled `false`. Returning `nil` follows the first connection. A route that returns `true` or `false` declares `output :result, type: :boolean, values: [true, false]`.
 6. For a type that awaits input, write the partial named in `drawn_by`, for example `app/views/flow_steps/_rating.html.erb`. It receives the display object as `step`. It renders only the input, since the page supplies the form, the Next button and the Back button. The input must be named `answers[<step id>]`, or the answer is not recorded:
 
    ```erb
@@ -104,6 +105,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    <%= number_field_tag "answers[#{step.id}]", nil, in: 1..step.scale %>
    ```
 
+   An answer is recorded as the string the visitor submitted. A compare step still reads a typed answer such as `"12"` as the number it spells, and an answer that is missing or is not a number makes it follow its `false` connection.
 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.
 
 ### Serve a host's flows from the app's own controller
@@ -136,8 +138,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 
    The controller inherits from the base controller set at install, uses the host's layout, visitor authorization and refusal methods, and only finds flows that belong to the named host. Pages it does not override use the engine's own views.
 4. Override only the private methods the developer's answers call for:
-   - `finished(answers, run)` — called when the visitor reaches the end. `answers` is the answers on the path taken, keyed by step id as symbols. `run` is the stored `EasyFlow::Run`, or `nil` when the flow keeps no record. It must render or redirect. Default: the engine's completion page.
-   - `start_run(flow)` — creates the run when a visitor starts a flow that saves each step. Call `super` and change the run it returns, for example to set its `owner` or `label`.
+   - `finished(answers, run)` — called when the visitor reaches the end. `answers` is the answers on the path taken, keyed by step id as symbols. `run` is the stored `EasyFlow::Run`, or `nil` when the admin set the flow to save nothing. A flow the admin set to save on finish gets its run created at this point. It must render or redirect. Default: the engine's completion page.
+   - `start_run(flow)` — creates the run when a visitor starts a flow the admin set to save each step. Call `super` and change the run it returns, for example to set its `owner` or `label`.
    - `runner_for(definition)` — returns the runner used for each step. Return a subclass of `EasyFlow::QuestionRunner` to change what the step and completion pages read from it.
 5. Visit `/<path>/<slug>` for a published flow and walk it to the end.
 
@@ -167,7 +169,9 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 ## 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`, `condition`, `switch`, `compare`.
 - Register class-based step types inside `to_prepare`. A type registered anywhere else is lost on code reload in development.
+- A type that routes declares the values its output takes, or the canvas offers no connections to label.
 - Always read a run against `run.pinned_definition`, never the flow's live version, since a run keeps the version it started on after a new one is published.
 - Always look flows and runs up through a host.
 - A step's input field is named `answers[<step id>]`. Any other name is ignored.

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, and step types the host app registers.
+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 branching on an answer or comparing a number, and step types the host app registers.
 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,32 +11,37 @@ 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 one step type, a question with a list of 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 or do 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 canvas drawing, turning on optional checks, and the admin pages.
+- **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.
 
 ## 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, 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.
 - If the question is only what a word below means, this page is the answer.
 
 ## Conventions
 
-- **Flow** — one guided path, found by its slug. It holds a working document the admin edits and a list of versions.
+- **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.
 - **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 processes the answers so far and records a result, and a step type may also decide its own routing.
-- **Question** — the built-in step type: a question text and a list of answers, each with a value, a label and a weight.
-- **Registry** — the list of step types the app has registered. A step whose type is not registered is not shown or run as that type.
+- **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.
+- **Start** and **End** — the built-in step types that begin and finish a flow.
+- **Question** — the built-in step type that asks the visitor: a question text and a list of answers, each with a value, a label and a weight.
+- **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.
+- **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.
 - **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.
 - **Answers** — the recorded state of a run, keyed by step id. The next step is always worked out from these answers and the connections in the pinned version.
-- **Checks** — optional warnings on a flow's shape an app can turn on: an answer value no connection routes, a path nothing follows, and a step that leads nowhere.
+- **Checks** — warnings on a flow's shape: an answer value no connection routes, a path nothing follows, and a step that leads nowhere. The engine turns all three on by default.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_flow
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - tylercschneider
@@ -90,6 +90,7 @@ files:
 - app/models/easy_flow/canvas.rb
 - app/models/easy_flow/change.rb
 - app/models/easy_flow/choice.rb
+- app/models/easy_flow/compare.rb
 - app/models/easy_flow/condition.rb
 - app/models/easy_flow/definition.rb
 - app/models/easy_flow/digest.rb