easy_flow 0.1.0

data/app/models/easy_flow/edit_history.rb

@@ -0,0 +1,73 @@
+module EasyFlow
+  class EditHistory
+    def initialize(flow)
+      @flow = flow
+    end
+
+    def undoable?
+      undoable.any?
+    end
+
+    def redoable?
+      undone.any?
+    end
+
+    def undoable
+      @flow.undo_history.to_a + @flow.changes_since_version.to_a
+    end
+
+    def undo_change
+      undone_change = undoable.last
+      return unless undone_change
+
+      @flow.update!(document: undone_change["before"],
+        undone_changes: undone + [ undone_change.merge("after" => @flow.document) ],
+        undo_history: @flow.undo_history.to_a[0...-1],
+        changes_since_version: @flow.changes_since_version.to_a[0...-1])
+    end
+
+    def redo_change
+      redone = undone.last
+      return unless redone
+
+      @flow.update!(document: redone["after"], undone_changes: undone[0...-1],
+        changes_since_version: @flow.changes_since_version.to_a + [ redone.except("after") ])
+    end
+
+    def record(edited, action, steps, before)
+      @flow.update!(document: edited.to_h, undone_changes: [],
+        changes_since_version: with(edited, action, steps, before))
+    end
+
+    def edit_document(payload)
+      @flow.update!(document: payload, undone_changes: [],
+        changes_since_version: @flow.changes_since_version.to_a + [ edited_by_hand ])
+    end
+
+    private
+
+    def with(edited, action, steps, before)
+      return @flow.changes_since_version.to_a unless action
+
+      @flow.changes_since_version.to_a +
+        [ { "action" => action.to_s, "steps" => steps.map(&:to_s),
+            "named" => steps.map { |id| named(edited, id) }, "before" => before } ]
+    end
+
+    def named(edited, id)
+      Name.of(edited.node(id.to_s) || document.node(id.to_s))
+    end
+
+    def document
+      Document.new(@flow.document || @flow.definition || {})
+    end
+
+    def undone
+      @flow.undone_changes.to_a
+    end
+
+    def edited_by_hand
+      { "action" => "edited", "steps" => [], "named" => [ "the definition" ], "before" => @flow.document }
+    end
+  end
+end

data/app/models/easy_flow/layout.rb

@@ -0,0 +1,86 @@
+module EasyFlow
+  class Layout
+    SPREAD = 2
+
+    def initialize(document)
+      @document = document
+    end
+
+    def positions
+      rows = depths
+      columns = columns_for(rows)
+
+      rows.to_h { |id, row| [ id, { "row" => row, "column" => columns[id] } ] }
+    end
+
+    private
+
+    def depths
+      walked = walk_from_entry
+
+      walked.merge(stranded(walked).index_with(next_row(walked)))
+    end
+
+    def walk_from_entry
+      seen = {}
+      frontier = starting_points.map { |id| [ id, 0 ] }
+
+      until frontier.empty?
+        id, depth = frontier.shift
+        next if seen.key?(id)
+
+        seen[id] = depth
+        @document.edges_from(id).each { |edge| frontier << [ edge.to, depth + 1 ] if known?(edge.to) }
+      end
+
+      seen
+    end
+
+    def starting_points
+      return [ @document.entry ] if known?(@document.entry)
+
+      arrived = @document.edges.map(&:to)
+      @document.nodes.map(&:id).reject { |id| arrived.include?(id) }
+    end
+
+    def columns_for(rows)
+      @columns = {}
+      @next_leaf = 0
+      rows.keys.each { |id| place(id, branches(rows)) }
+      @columns
+    end
+
+    def branches(rows)
+      claimed = {}
+
+      rows.keys.to_h do |id|
+        mine = @document.edges_from(id).map(&:to).uniq
+          .select { |child| rows[child] == rows[id] + 1 && !claimed.key?(child) }
+        mine.each { |child| claimed[child] = true }
+        [ id, mine ]
+      end
+    end
+
+    def place(id, branches)
+      return @columns[id] if @columns.key?(id)
+
+      mine = branches[id].to_a
+      return @columns[id] = (@next_leaf += SPREAD) - SPREAD if mine.empty?
+
+      spans = mine.map { |child| place(child, branches) }
+      @columns[id] = (spans.min + spans.max) / 2
+    end
+
+    def stranded(walked)
+      @document.nodes.map(&:id).uniq - walked.keys
+    end
+
+    def next_row(walked)
+      (walked.values.max || -1) + 1
+    end
+
+    def known?(id)
+      @document.node(id).present?
+    end
+  end
+end

data/app/models/easy_flow/name.rb

@@ -0,0 +1,13 @@
+module EasyFlow
+  module Name
+    def self.of(node, registry = EasyFlow.registry)
+      return "" unless node
+
+      named(node, registry) || node.id
+    end
+
+    def self.named(node, registry)
+      registry.fetch(node.type).name_of(node) if registry.registered?(node.type)
+    end
+  end
+end

data/app/models/easy_flow/node.rb

@@ -0,0 +1,3 @@
+module EasyFlow
+  Node = Data.define(:id, :type, :config)
+end

data/app/models/easy_flow/output.rb

@@ -0,0 +1,21 @@
+module EasyFlow
+  Output = Data.define(:name, :label, :type, :values, :from) do
+    def initialize(name:, label: nil, type: :string, values: nil, from: nil)
+      raise UnknownOutputType, "#{type} is not one of #{OUTPUT_TYPES.join(', ')}" unless OUTPUT_TYPES.include?(type)
+
+      super(name: name, label: label.presence || name.to_s.humanize, type: type, values: values, from: from)
+    end
+
+    def values_for(node)
+      Array(values.respond_to?(:call) ? values.call(node) : values).map { |value| taken(value) }
+    end
+
+    private
+
+    def taken(value)
+      return value if value.is_a?(Hash)
+
+      { "value" => value, "label" => value.to_s }
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module EasyFlow
+  module Progress
+    class Kept
+      def initialize(run)
+        @run = run
+      end
+
+      def definition
+        @run.pinned_definition
+      end
+
+      def recorded
+        @run.recorded
+      end
+
+      def record(id, value)
+        @run.record(id.to_sym, value)
+      end
+
+      def finish(_state)
+        @run
+      end
+
+      def discard_last
+        @run.discard_last
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module EasyFlow
+  module Progress
+    class Loose
+      def initialize(flow, answers, definition = nil)
+        @flow = flow
+        @answers = answers.to_h.symbolize_keys
+        @definition = definition
+      end
+
+      def definition
+        @definition || @flow.live_definition
+      end
+
+      def recorded
+        @answers
+      end
+
+      def record(id, value)
+        @answers = @answers.merge(id.to_sym => value)
+      end
+
+      def finish(state)
+        return unless @flow.on_finish?
+
+        Run.start(@flow).tap { |run| run.update!(recorded: state) }
+      end
+
+      def discard_last
+        last = Runner.new(@flow.live_definition).state_on_path(@answers).keys.last
+
+        @answers = @answers.except(last) if last
+      end
+    end
+  end
+end

data/app/models/easy_flow/progress.rb

@@ -0,0 +1,9 @@
+module EasyFlow
+  module Progress
+    def self.for(flow, run: nil, answers: {}, definition: nil)
+      return Kept.new(run) if run
+
+      Loose.new(flow, answers, definition)
+    end
+  end
+end

data/app/models/easy_flow/question_runner.rb

@@ -0,0 +1,13 @@
+module EasyFlow
+  class QuestionRunner < Runner
+    def question_text(id)
+      Steps::Question.asked(step(id)&.config)
+    end
+
+    def choice_label(id, value)
+      chosen = Steps::Question.choices_in(step(id)).find { |choice| choice.value == value }
+
+      chosen&.label.presence || value
+    end
+  end
+end

data/app/models/easy_flow/registry.rb

@@ -0,0 +1,23 @@
+module EasyFlow
+  class Registry
+    def initialize
+      @step_types = {}
+    end
+
+    def register(step_type)
+      @step_types[step_type.id.to_sym] = step_type
+    end
+
+    def fetch(id)
+      @step_types.fetch(id.to_sym) { raise UnknownStepType, "no step type registered as #{id}" }
+    end
+
+    def registered?(id)
+      id.present? && @step_types.key?(id.to_sym)
+    end
+
+    def step_types
+      @step_types.values
+    end
+  end
+end

data/app/models/easy_flow/run.rb

@@ -0,0 +1,46 @@
+module EasyFlow
+  class Run < ApplicationRecord
+    self.table_name = "easy_flow_runs"
+
+    belongs_to :flow, class_name: "EasyFlow::Definition"
+    belongs_to :definition_version, class_name: "EasyFlow::Version"
+    belongs_to :owner, polymorphic: true, optional: true
+
+    def self.start(flow)
+      create!(flow: flow, definition_version: flow.live_version)
+    end
+
+    def record(step_id, value)
+      update!(recorded: recorded.merge(step_id => value))
+    end
+
+    def recorded
+      super.to_h.symbolize_keys
+    end
+
+    def pinned_definition
+      definition_version.definition.to_h
+    end
+
+    def next_step(state)
+      digest.next_step(state.transform_keys(&:to_s))
+    end
+
+    def walked(state)
+      digest.state_on_path(state.transform_keys(&:to_s))
+    end
+
+    def digest
+      @digest ||= Digest.new(Document.new(pinned_definition))
+    end
+
+    def discard_last
+      last = walked(recorded).keys.map(&:to_sym).last
+      update!(recorded: recorded.except(last)) if last
+    end
+
+    def pinned_steps
+      Array(definition_version.definition.to_h["nodes"]).index_by { |node| node["id"] }
+    end
+  end
+end

data/app/models/easy_flow/runner.rb

@@ -0,0 +1,63 @@
+module EasyFlow
+  class Runner
+    def initialize(document, registry: EasyFlow.registry)
+      @document = document.to_h
+      @registry = registry
+      @digest = Digest.new(Document.new(@document, registry: registry), registry: registry)
+    end
+
+    def slug
+      @document["slug"]
+    end
+
+    def headline
+      @document["headline"]
+    end
+
+    def steps
+      @digest.steps
+    end
+
+    def step(id)
+      @digest.step(id.to_s)
+    end
+
+    def next_step(state)
+      shown(@digest.next_step(named(state)))
+    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)))
+      end
+    end
+
+    def drawing_at(state)
+      Drawing.of(@digest.next_step(named(state)), @registry)
+    end
+
+    def state_on_path(state)
+      @digest.state_on_path(named(state)).symbolize_keys
+    end
+
+    def steps_on_path(state)
+      state_on_path(state).keys.map { |id| shown(@digest.step(id.to_s)) }
+    end
+
+    private
+
+    def acts?(node)
+      @registry.registered?(node.type) && @registry.fetch(node.type).acts?
+    end
+
+    def shown(node)
+      return node unless node && @registry.registered?(node.type)
+
+      @registry.fetch(node.type).display_of(node) || node
+    end
+
+    def named(state)
+      state.transform_keys(&:to_s)
+    end
+  end
+end

data/app/models/easy_flow/settings.rb

@@ -0,0 +1,78 @@
+module EasyFlow
+  class Settings
+    attr_reader :fields, :labels, :record_fields, :record_labels, :choices, :drawn_from, :outputs_of
+
+    def initialize(fields: {}, labels: {}, record_fields: {}, record_labels: {}, choices: {},
+      limits: {}, checks: {}, required: [], drawn_from: {}, outputs_of: {})
+      @fields = fields
+      @labels = labels
+      @record_fields = record_fields
+      @record_labels = record_labels
+      @choices = choices
+      @limits = limits
+      @checks = checks
+      @required = required
+      @drawn_from = drawn_from
+      @outputs_of = outputs_of
+    end
+
+    def naming_steps
+      fields.select { |_name, type| type == :previous_step }.keys
+    end
+
+    def required
+      fields.keys.select { |name| @required.include?(name) || naming_steps.include?(name) }
+    end
+
+    def requirements_for(config)
+      naming_steps.map { |name| config.to_h[name.to_s] }.compact_blank
+    end
+
+    def coerce(config)
+      config.to_h.to_h { |name, value| [ name, cast(fields[name.to_sym], value, record_fields[name.to_sym]) ] }
+    end
+
+    def objections(config)
+      config.to_h.flat_map { |name, value| objections_to(name.to_sym, value) }.compact
+    end
+
+    private
+
+    def objections_to(name, value)
+      [ unoffered(name, value), over_limit(name, value), refused(name, value) ]
+    end
+
+    def unoffered(name, value)
+      offered = choices[name]
+      return unless offered
+
+      stray = Array(value).find { |chosen| offered.exclude?(chosen) }
+      "#{labels[name]} does not offer #{stray}" if stray
+    end
+
+    def over_limit(name, value)
+      allowed = @limits[name]
+      return unless allowed && Array(value).size > allowed
+
+      "#{labels[name]} takes at most #{allowed}"
+    end
+
+    def refused(name, value)
+      @checks[name]&.call(value)
+    end
+
+    def cast(type, value, holds = nil)
+      case type
+      when :integer then Integer(value, exception: false)
+      when :float then Float(value, exception: false)
+      when :boolean then ActiveModel::Type::Boolean.new.cast(value).present?
+      when :list then Array(value).map { |entry| cast_entry(entry, holds.to_h) }
+      else value
+      end
+    end
+
+    def cast_entry(entry, holds)
+      entry.to_h.to_h { |name, value| [ name, cast(holds[name.to_sym], value) ] }
+    end
+  end
+end

data/app/models/easy_flow/start.rb

@@ -0,0 +1,11 @@
+module EasyFlow
+  class Start
+    include Step
+
+    step_name "Start"
+
+    begins_here
+
+    names_by { |_node| "Start" }
+  end
+end

data/app/models/easy_flow/step.rb

@@ -0,0 +1,40 @@
+module EasyFlow
+  module Step
+    extend ActiveSupport::Concern
+
+    WORDS = (StepType::Declaration.public_instance_methods(false) - [ :to_step_type ]).freeze
+    BEHAVIOURS = %i[route process].freeze
+
+    included do
+      class_attribute :declarations, default: []
+    end
+
+    class_methods do
+      WORDS.each do |word|
+        define_method(word) do |*arguments, **options, &block|
+          self.declarations += [ [ word, arguments, options, block ] ]
+        end
+      end
+
+      def step_type
+        spoken = declarations + behaviours
+        StepType.define(step_type_id) do
+          spoken.each { |word, arguments, options, block| public_send(word, *arguments, **options, &block) }
+        end
+      end
+
+      def behaviours
+        BEHAVIOURS.select { |word| method_defined?(word) }
+          .map { |word| [ word, [], {}, ->(node, state) { new.public_send(word, node, state) } ] }
+      end
+
+      def register(registry = EasyFlow.registry)
+        registry.register(step_type)
+      end
+
+      def step_type_id
+        name.demodulize.underscore.to_sym
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+module EasyFlow
+  class StepType
+    class Declaration
+      def initialize(id)
+        @id = id
+        @step_name = id.to_s
+        @fields = {}
+        @labels = {}
+        @record_fields = {}
+        @record_labels = {}
+        @choices = {}
+        @limits = {}
+        @checks = {}
+        @drawn_from = {}
+        @outputs_of = {}
+        @declared_outputs = []
+        @required = []
+        @awaits_input = false
+        @ends_here = false
+        @begins_here = false
+      end
+
+      def output(name, type: :string, label: nil, values: nil, from: nil)
+        @declared_outputs += [ Output.new(name: name, type: type, label: label, values: values, from: from) ]
+      end
+
+      def displays_by(&display)
+        @display = display
+      end
+
+      def drawn_by(template)
+        @drawn_by = template
+      end
+
+      def process(&behaviour)
+        @behaviour = behaviour
+      end
+
+      def route(&routing)
+        @routing = routing
+      end
+
+      def step_name(value)
+        @step_name = value
+      end
+
+      def awaits_input
+        @awaits_input = true
+      end
+
+      def ends_here
+        @ends_here = true
+      end
+
+      def begins_here
+        @begins_here = true
+      end
+
+      def names_by(field = nil, &naming)
+        @naming_field = field
+        @naming = naming
+      end
+
+      def setting(name, type: nil, from: nil, outputs_of: nil, label: nil, options: nil, limit: nil, check: nil, required: false, &entries)
+        type ||= :from_step if from
+        type ||= :from_step if outputs_of
+        raise UnknownFieldType, "#{type} is not one of #{FIELD_TYPES.join(', ')}" unless FIELD_TYPES.include?(type)
+
+        @drawn_from[name] = from if from
+        @outputs_of[name] = outputs_of if outputs_of
+        @required += [ name ] if required
+
+        declare_entries(name, entries) if type == :list
+        declare_choices(name, type, options)
+        @limits[name] = limit if limit
+        @checks[name] = check if check
+        @labels[name] = label.presence || name.to_s.humanize
+        @fields[name] = type
+      end
+
+      protected
+
+      attr_reader :fields, :labels
+
+      private
+
+      def declare_choices(name, type, options)
+        return @choices[name] = options if options.present?
+        raise UnknownFieldType, "a #{type} must offer options" if %i[select multi_select].include?(type)
+      end
+
+      def declare_entries(name, entries)
+        raise UnknownFieldType, "a list must say what an entry holds" if entries.nil?
+
+        declared = Declaration.new(:entry).tap { |entry| entry.instance_eval(&entries) }
+        @record_fields[name] = declared.fields
+        @record_labels[name] = declared.labels
+      end
+
+      public
+
+      def to_step_type
+        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)
+      end
+
+      def settings
+        Settings.new(fields: @fields, labels: @labels, record_fields: @record_fields,
+          record_labels: @record_labels, choices: @choices, limits: @limits, checks: @checks,
+          required: @required, drawn_from: @drawn_from, outputs_of: @outputs_of)
+      end
+    end
+  end
+end