easy_flow 0.4.8 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f7ac7fa5bfb54fd32b37779b0ec07dcaf754d8d242fedac33fffa58e1c49d22
-  data.tar.gz: 9947469ec0272eccb7624372e102e6b60f9a93ebbe08572846246f8ae956eb56
+  metadata.gz: 310df5972d6ca11a6862e8c101b79f8802adbe620ee90e3c8764cda70feb9492
+  data.tar.gz: c43a02f417356eb7bf31e2e53fa220a4d32b7fefed055ed031dda114eccec951
 SHA512:
-  metadata.gz: 2ec1059bd29bcd076aef6df9a4f713690ebd7e8bb786e1c05bf51d9991b23f497c3e83bfb4aad12063168b9d5fdf96f4a265dbe1cb496a7fbe5a4238053db9aa
-  data.tar.gz: ea9a2e1eabb38ccad3426bb487f8a9e1933eb83e4c4d98920868e926e5f963d7eefd4aeed3604663f2c1b47e5651c84f458a19a5fe2abd044d664fd755634ef4
+  metadata.gz: 82e5b5eede06952c31b553577668d70499b828e576f5acc2e96964a30f8c897c6762d8e450674d5774d2c54034c0309019cf68138ddc45d9de48b165659bfe29
+  data.tar.gz: 0ad147aae3a60c96b225122d43d7f73e570c275b101b7c74db0bf00389ac01e927026ae5428925c3f9f8887d88a14f1266d82cd5299972b4f53dba7b75e32f9c

data/app/controllers/concerns/easy_flow/manage/draws_canvas.rb

@@ -6,7 +6,7 @@ module EasyFlow
       private
 
       def canvas_payload(flow)
-        Canvas.new(canvas_document(flow)).to_h
+        Canvas.new(canvas_document(flow), host: flow_host).to_h
           .merge("undoable" => flow.edit_history.undoable?, "redoable" => flow.edit_history.redoable?,
                  "changes" => listed_changes(flow), "flow" => flow_details(flow))
       end

data/app/models/easy_flow/canvas.rb

@@ -1,8 +1,9 @@
 module EasyFlow
   class Canvas
-    def initialize(document, registry: EasyFlow.registry)
+    def initialize(document, registry: EasyFlow.registry, host: nil)
       @document = document
       @registry = registry
+      @host = host
     end
 
     def to_h
@@ -81,7 +82,7 @@ module EasyFlow
     end
 
     def palette
-      @registry.step_types.reject(&:begins_here?).map do |step_type|
+      @registry.step_types.reject(&:begins_here?).select { |step_type| @host.nil? || step_type.ends_here? || @host.offers?(step_type.id) }.map do |step_type|
         { "type" => step_type.id.to_s, "label" => step_type.step_name,
           "fields" => step_type.settings.fields.transform_keys(&:to_s).transform_values(&:to_s),
           "labels" => step_type.settings.labels.transform_keys(&:to_s),

data/lib/easy_flow/host.rb

@@ -1,7 +1,7 @@
 module EasyFlow
   class Host
     attr_reader :name
-    attr_writer :layout, :admin_layout
+    attr_writer :layout, :admin_layout, :offers
     attr_accessor :admin_authentication_method, :visitor_authorization_method, :refusal_method
 
     def initialize(name)
@@ -23,5 +23,9 @@ module EasyFlow
     def set_up?
       true
     end
+
+    def offers?(step_type)
+      @offers.nil? || @offers.map(&:to_s).include?(step_type.to_s)
+    end
   end
 end

data/lib/easy_flow/version.rb

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

data/the_local/agents/easy_flow-develop.md

@@ -73,18 +73,19 @@ 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):
+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.
+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:, 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. `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 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 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.
+   - `waits_until { |node, state| ... }` — the run stops at this step until the block returns a truthy value. See step 8.
    - `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.
    - `drawn_by "<partial>"` — the partial that draws this type for a visitor. Without it the host's default drawing is used, which expects `step.id`, `step.text` and `step.choices`, so a type with its own display shape needs its own partial.
-5. For a type that computes or routes, define instance methods on the class (or `process { |node, state| ... }` / `route { |node, state| ... }` in the block form):
+6. For a type that computes or routes, define instance methods on the class (or `process { |node, state| ... }` / `route { |node, state| ... }` in the block form):
 
    ```ruby
    def process(node, state)
@@ -101,7 +102,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `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.
    - 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:
+7. 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
    <%= label_tag "answers[#{step.id}]", step.text %>
@@ -118,7 +119,7 @@ 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. For a type that waits, declare `waits_until` with a block that says whether what the step waits for has happened:
+8. For a type that waits, declare `waits_until` with a block that says whether what the step waits for has happened:
 
    ```ruby
    module FlowSteps
@@ -142,7 +143,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - 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.
+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.
 
 ### Serve a host's flows from the app's own controller
 
@@ -208,6 +209,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - 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.
+- 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.
 - An `options:` lambda is passed nothing, and one list is offered on every host's canvas, so it cannot narrow the options by admin, account or host.
 - 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.
@@ -218,4 +221,4 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - 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.
+- The engine installs, mounts and configures hosts, the step types each host offers, 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, 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.
+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 and the step types each offers its admins, 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
 ---
@@ -17,12 +17,12 @@ Reach for it when an app needs a questionnaire, an intake form, or any decision
 
 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-install** owns putting the engine into an app: its migrations, mounting it, choosing the controller it inherits from, naming hosts and the step types each one offers, choosing the default step drawing, the flow checks, and the admin pages.
 - **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 get easy_flow running in an app, or to change how it is configured, including which step types a host's admins can add, use **easy_flow-install**.
 - 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.
@@ -48,7 +48,9 @@ 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. 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.
+- **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. 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.
+- **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.
 - **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.
 - **Refused answer** — an answer the step's answer check turned down. Nothing is recorded for that step, and the visitor is shown the same step again with the check's message. This works the same whether the flow keeps a stored run or carries its answers in the page.

data/the_local/agents/easy_flow-install.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-install
-description: Use to hook easy_flow into a project — copying and running its migrations, mounting the engine for each host, setting the controller it inherits from, declaring hosts with their layouts and access methods, choosing the default step drawing, turning on optional checks, and reaching the admin pages.
+description: Use to hook easy_flow into a project — copying and running its migrations, mounting the engine for each host, setting the controller it inherits from, declaring hosts with their layouts, access methods and the step types each offers, choosing the default step drawing, turning on optional checks, and reaching the admin pages.
 tools: Bash, Read, Edit
 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
 ---
@@ -16,7 +16,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - `bin/rails easy_flow:install:migrations` — copies the engine's migrations into the host's `db/migrate`, creating the flow, version and run tables.
 - `mount EasyFlow::Engine` — the route that serves one host's visitor pages and admin pages under a path, with the host named in `defaults: { easy_flow_host: "<host>" }`.
 - `EasyFlow.base_controller=` — the name, as a string, of the host controller every engine controller inherits from. Defaults to `"ActionController::Base"`.
-- `EasyFlow.host` — declares a named host with its visitor layout, admin layout, admin authentication method, visitor authorization method and refusal method.
+- `EasyFlow.host` — declares a named host with its visitor layout, admin layout, admin authentication method, visitor authorization method, refusal method, and the step types its admins can add on the canvas.
 - `EasyFlow.draws_with` — the partial that draws a visitor's step when the step's type names none. Defaults to the engine's own `easy_flow/steps/choosing`.
 - `EasyFlow.check` — turns on an optional flow check: `:unrouted_value`, `:unfollowed_path` or `:dead_end`.
 - `/manage/flows` — the admin pages, under each mount path, where flows are listed, created, drawn on the canvas, previewed and published.
@@ -42,6 +42,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
      host.admin_authentication_method = :authenticate_admin!
      host.visitor_authorization_method = :easy_flow_visitor_permitted?
      host.refusal_method = :refuse_flow
+     host.offers = %i[question condition switch compare]
    end
    ```
 
@@ -50,6 +51,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `admin_authentication_method` — a method on the base controller, called with no arguments before every admin page. With none set, the admin pages are open to anyone.
    - `visitor_authorization_method` — a method on the base controller, called with the flow, returning true when the visitor may run it. With none set, every visitor is refused.
    - `refusal_method` — a method on the base controller, called with the refusal error when a visitor is refused or a flow is unpublished or withdrawn. With none set, the response is `404 Not Found`.
+   - `offers` — the step types this host's admins can add from the canvas palette, as a list of step type names. With none set, every registered step type is offered. The engine's own names are `question`, `condition`, `switch` and `compare`, A step type the app declares is named by the id passed to `EasyFlow.step`, or after its class when it is a step class, so `Steps::Notify` is `notify`. The End step is offered whether it is listed or not, and the Start step is never offered. Ask the developer which step types each host should offer.
 
    Each method named here must exist on the base controller. Ask the developer to point at it or write it. Do not invent its logic.
 7. Mount the engine in `config/routes.rb`, once per host. The host name in `defaults` must match a name declared in step 6. When there is more than one mount, give each an `as:` name:
@@ -74,5 +76,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - After install, check that `<mount path>/manage/flows` shows the flow list and that a new flow opens on the canvas. If the canvas is blank, check that the admin layout calls `yield :head`.
 - After publishing a flow, check that `<mount path>/<slug>` shows it to a visitor who passes the host's visitor authorization method.
 - After upgrading easy_flow, run `bin/rails easy_flow:install:migrations` again and then `bin/rails db:migrate`. Only migrations the app does not already have are copied.
+- After setting a host's `offers`, check that the canvas palette on that host's `<mount path>/manage/flows` lists only those step types and End.
+- Taking a step type off a host's `offers` removes it from the palette only. Steps of that type already in the host's flows stay in them and keep running.
 - The initializer runs once at boot, so a change to it needs a server restart.
 - Declaring step types, serving a host's flows from the app's own controllers and routes, and reading runs and answers are out of scope here. They belong to the `easy_flow-develop` local.

metadata

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