flowengine-rails 0.1.0

data/app/controllers/flow_engine/sessions_controller.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  class SessionsController < ApplicationController
+    before_action :set_session, only: %i[show update completed abandon]
+
+    def new
+      @definitions = FlowEngine::FlowDefinition.active.order(:name)
+      @definition_id = params[:definition_id]
+    end
+
+    def create
+      definition = FlowEngine::FlowDefinition.find(params[:definition_id])
+      engine = FlowEngine::Engine.new(definition.parsed_definition)
+      state = engine.to_state
+
+      session = FlowEngine::FlowSession.create!(
+        flow_definition: definition,
+        current_step_id: state[:current_step_id]&.to_s,
+        answers: {},
+        history: state[:history].map(&:to_s),
+        status: "in_progress"
+      )
+
+      redirect_to session_path(session, embed_params)
+    end
+
+    def show
+      if @flow_session.completed?
+        redirect_to completed_session_path(@flow_session, embed_params)
+        return
+      end
+
+      @node = @flow_session.current_node
+      @progress = @flow_session.progress_percentage
+    end
+
+    def update
+      unless @flow_session.in_progress?
+        redirect_to session_path(@flow_session, embed_params)
+        return
+      end
+
+      answer_value = parse_answer
+      @flow_session.advance!(answer_value)
+
+      if @flow_session.completed?
+        redirect_to completed_session_path(@flow_session, embed_params)
+      else
+        redirect_to session_path(@flow_session, embed_params)
+      end
+    end
+
+    def completed
+      @result = @flow_session.result_json
+    end
+
+    def abandon
+      @flow_session.abandon!
+      redirect_to new_session_path(embed_params), notice: "Session abandoned."
+    end
+
+    private
+
+    def set_session
+      @flow_session = FlowEngine::FlowSession.find(params[:id])
+    end
+
+    def embed_params
+      embed_mode? ? { embed: "true" } : {}
+    end
+
+    def parse_answer
+      node = @flow_session.current_node
+      return params[:answer] unless node
+
+      case node.type
+      when :multi_select
+        params[:answer_values] || []
+      when :number_matrix
+        (params[:answer_fields] || {}).to_unsafe_h.transform_values(&:to_i)
+      when :number
+        params[:answer].to_i
+      when :boolean
+        params[:answer] == "true"
+      else
+        params[:answer]
+      end
+    end
+  end
+end

data/app/helpers/flow_engine/sessions_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module SessionsHelper
+    STEP_PARTIALS = {
+      multi_select: "flow_engine/sessions/steps/multi_select",
+      single_select: "flow_engine/sessions/steps/single_select",
+      number_matrix: "flow_engine/sessions/steps/number_matrix",
+      text: "flow_engine/sessions/steps/text",
+      number: "flow_engine/sessions/steps/number",
+      boolean: "flow_engine/sessions/steps/boolean",
+      display: "flow_engine/sessions/steps/display"
+    }.freeze
+
+    def render_step(node, form)
+      partial = STEP_PARTIALS.fetch(node.type, "flow_engine/sessions/steps/unknown")
+      render partial: partial, locals: { node: node, form: form }
+    end
+  end
+end

data/app/models/flow_engine/application_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name_prefix = "flow_engine_"
+  end
+end

data/app/models/flow_engine/flow_definition.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  class FlowDefinition < ApplicationRecord
+    self.table_name = "flow_engine_definitions"
+
+    has_many :flow_sessions, dependent: :restrict_with_error, foreign_key: :definition_id, inverse_of: :flow_definition
+
+    validates :name, presence: true
+    validates :version, presence: true,
+                        numericality: { only_integer: true, greater_than: 0 },
+                        uniqueness: { scope: :name }
+    validates :dsl, presence: true
+    validate :dsl_must_parse
+
+    attr_accessor :skip_auto_version
+
+    before_validation :auto_increment_version, on: :create, unless: :skip_auto_version
+
+    scope :active, -> { where(active: true) }
+    scope :by_name, ->(name) { where(name: name) }
+    scope :latest_version, ->(name) { by_name(name).order(version: :desc).first }
+
+    def parsed_definition
+      @parsed_definition ||= FlowEngine::Rails::DslLoader.load(dsl, cache_key: cache_key_for_dsl)
+    end
+
+    def activate!
+      transaction do
+        self.class.where(name: name, active: true).where.not(id: id).update_all(active: false)
+        update!(active: true)
+      end
+    end
+
+    def deactivate!
+      update!(active: false)
+    end
+
+    def readonly?
+      flow_sessions.exists? && persisted? && !new_record?
+    end
+
+    def mermaid_diagram
+      exporter = FlowEngine::Graph::MermaidExporter.new(parsed_definition)
+      exporter.export
+    end
+
+    def step_ids
+      parsed_definition.step_ids
+    end
+
+    def total_steps
+      step_ids.size
+    end
+
+    private
+
+    def cache_key_for_dsl
+      "definition:#{id}:v#{version}" if persisted?
+    end
+
+    def auto_increment_version
+      max_version = self.class.where(name: name).maximum(:version) || 0
+      self.version = max_version + 1
+    end
+
+    def dsl_must_parse
+      return if dsl.blank?
+
+      FlowEngine::Rails::DslLoader.load(dsl)
+    rescue FlowEngine::Errors::Error => e
+      errors.add(:dsl, "is invalid: #{e.message}")
+    end
+  end
+end

data/app/models/flow_engine/flow_session.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  class FlowSession < ApplicationRecord
+    self.table_name = "flow_engine_sessions"
+
+    belongs_to :flow_definition, foreign_key: :definition_id, inverse_of: :flow_sessions
+
+    validates :status, presence: true, inclusion: { in: %w[in_progress completed abandoned] }
+
+    scope :in_progress, -> { where(status: "in_progress") }
+    scope :completed, -> { where(status: "completed") }
+    scope :abandoned, -> { where(status: "abandoned") }
+
+    def engine
+      state = {
+        current_step_id: current_step_id,
+        answers: answers || {},
+        history: history || []
+      }
+      FlowEngine::Engine.from_state(flow_definition.parsed_definition, state)
+    end
+
+    def advance!(answer_value)
+      eng = engine
+      eng.answer(answer_value)
+      persist_engine_state!(eng)
+    end
+
+    def abandon!
+      update!(status: "abandoned")
+    end
+
+    def in_progress?
+      status == "in_progress"
+    end
+
+    def completed?
+      status == "completed"
+    end
+
+    def abandoned?
+      status == "abandoned"
+    end
+
+    def finished?
+      completed? || abandoned?
+    end
+
+    def current_node
+      return nil if current_step_id.blank?
+
+      flow_definition.parsed_definition.step(current_step_id.to_sym)
+    rescue FlowEngine::UnknownStepError
+      nil
+    end
+
+    def progress_percentage
+      total = flow_definition.total_steps
+      return 0 if total.zero?
+
+      completed_count = (history || []).size
+      [(completed_count.to_f / total * 100).round, 100].min
+    end
+
+    def result_json
+      {
+        definition_name: flow_definition.name,
+        definition_version: flow_definition.version,
+        answers: answers,
+        history: history,
+        status: status,
+        completed_at: updated_at&.iso8601
+      }
+    end
+
+    private
+
+    def persist_engine_state!(eng)
+      state = eng.to_state
+      new_status = eng.finished? ? "completed" : "in_progress"
+
+      update!(
+        current_step_id: state[:current_step_id]&.to_s,
+        answers: state[:answers].transform_keys(&:to_s),
+        history: state[:history].map(&:to_s),
+        status: new_status
+      )
+
+      fire_completion_callback if new_status == "completed"
+    end
+
+    def fire_completion_callback
+      callback = FlowEngine::Rails.configuration.on_session_complete
+      callback&.call(self)
+    end
+  end
+end

data/app/views/flow_engine/admin/definitions/_form.html.erb

@@ -0,0 +1,27 @@
+<%= form_with model: [:admin, definition], url: url, method: method, local: true do |form| %>
+  <% if definition.errors.any? %>
+    <div class="fe-errors">
+      <h3><%= pluralize(definition.errors.count, "error") %> prevented this definition from being saved:</h3>
+      <ul>
+        <% definition.errors.full_messages.each do |msg| %>
+          <li><%= msg %></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="fe-form-group">
+    <%= form.label :name, class: "fe-label" %>
+    <%= form.text_field :name, class: "fe-input" %>
+  </div>
+
+  <div class="fe-form-group">
+    <%= form.label :dsl, "DSL Definition", class: "fe-label" %>
+    <%= form.text_area :dsl, rows: 20, class: "fe-input fe-input--textarea fe-input--code" %>
+  </div>
+
+  <div class="fe-form-group">
+    <%= form.submit class: "fe-btn fe-btn--primary" %>
+    <%= link_to "Cancel", flow_engine.admin_definitions_path, class: "fe-btn" %>
+  </div>
+<% end %>

data/app/views/flow_engine/admin/definitions/edit.html.erb

@@ -0,0 +1,5 @@
+<h1>Edit: <%= @definition.name %> v<%= @definition.version %></h1>
+
+<%= render "form", definition: @definition,
+                   url: flow_engine.admin_definition_path(@definition),
+                   method: :patch %>

data/app/views/flow_engine/admin/definitions/index.html.erb

@@ -0,0 +1,41 @@
+<h1>Flow Definitions</h1>
+
+<%= link_to "New Definition", flow_engine.new_admin_definition_path, class: "fe-btn fe-btn--primary" %>
+
+<% @grouped.each do |name, versions| %>
+  <div class="fe-definition-group">
+    <h2><%= name %></h2>
+    <table class="fe-table">
+      <thead>
+        <tr>
+          <th>Version</th>
+          <th>Active</th>
+          <th>Sessions</th>
+          <th>Created</th>
+          <th>Actions</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% versions.each do |definition| %>
+          <tr>
+            <td>v<%= definition.version %></td>
+            <td><%= definition.active? ? "Yes" : "No" %></td>
+            <td><%= definition.flow_sessions.count %></td>
+            <td><%= definition.created_at.strftime("%Y-%m-%d %H:%M") %></td>
+            <td>
+              <%= link_to "View", flow_engine.admin_definition_path(definition) %>
+              <% unless definition.readonly? %>
+                | <%= link_to "Edit", flow_engine.edit_admin_definition_path(definition) %>
+              <% end %>
+              <% if definition.active? %>
+                | <%= link_to "Deactivate", flow_engine.deactivate_admin_definition_path(definition), data: { turbo_method: :post } %>
+              <% else %>
+                | <%= link_to "Activate", flow_engine.activate_admin_definition_path(definition), data: { turbo_method: :post } %>
+              <% end %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% end %>

data/app/views/flow_engine/admin/definitions/mermaid.html.erb

@@ -0,0 +1,9 @@
+<h1>Mermaid Diagram: <%= @definition.name %> v<%= @definition.version %></h1>
+
+<div class="fe-mermaid">
+  <pre class="fe-code"><code><%= @diagram %></code></pre>
+</div>
+
+<p>
+  <%= link_to "Back", flow_engine.admin_definition_path(@definition), class: "fe-btn" %>
+</p>

data/app/views/flow_engine/admin/definitions/new.html.erb

@@ -0,0 +1,5 @@
+<h1>New Flow Definition</h1>
+
+<%= render "form", definition: @definition,
+                   url: flow_engine.admin_definitions_path,
+                   method: :post %>

data/app/views/flow_engine/admin/definitions/show.html.erb

@@ -0,0 +1,25 @@
+<h1><%= @definition.name %> <small>v<%= @definition.version %></small></h1>
+
+<div class="fe-definition-detail">
+  <p><strong>Status:</strong> <%= @definition.active? ? "Active" : "Inactive" %></p>
+  <p><strong>Sessions:</strong> <%= @definition.flow_sessions.count %></p>
+  <p><strong>Steps:</strong> <%= @definition.total_steps %></p>
+
+  <div class="fe-definition-detail__actions">
+    <% if @definition.active? %>
+      <%= link_to "Deactivate", flow_engine.deactivate_admin_definition_path(@definition), method: :post, data: { turbo_method: :post }, class: "fe-btn" %>
+    <% else %>
+      <%= link_to "Activate", flow_engine.activate_admin_definition_path(@definition), method: :post, data: { turbo_method: :post }, class: "fe-btn fe-btn--primary" %>
+    <% end %>
+
+    <% unless @definition.readonly? %>
+      <%= link_to "Edit", flow_engine.edit_admin_definition_path(@definition), class: "fe-btn" %>
+    <% end %>
+
+    <%= link_to "Mermaid Diagram", flow_engine.mermaid_admin_definition_path(@definition), class: "fe-btn" %>
+    <%= link_to "Back", flow_engine.admin_definitions_path, class: "fe-btn" %>
+  </div>
+
+  <h2>DSL Source</h2>
+  <pre class="fe-code"><code><%= @definition.dsl %></code></pre>
+</div>

data/app/views/flow_engine/sessions/completed.html.erb

@@ -0,0 +1,34 @@
+<div class="fe-completed">
+  <h1>Flow Complete</h1>
+
+  <div class="fe-completed__summary">
+    <h2><%= @flow_session.flow_definition.name %> — Results</h2>
+
+    <table class="fe-table">
+      <thead>
+        <tr>
+          <th>Step</th>
+          <th>Answer</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% (@flow_session.answers || {}).each do |step_id, answer| %>
+          <tr>
+            <td><%= step_id %></td>
+            <td><%= answer.is_a?(Hash) || answer.is_a?(Array) ? answer.to_json : answer %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+
+  <% if embed_mode? %>
+    <script>
+      window.parent.postMessage({
+        type: 'flowengine:completed',
+        sessionId: '<%= @flow_session.id %>',
+        answers: <%= raw @result.to_json %>
+      }, '*');
+    </script>
+  <% end %>
+</div>

data/app/views/flow_engine/sessions/new.html.erb

@@ -0,0 +1,17 @@
+<h1>Start a New Flow</h1>
+
+<% if @definitions.any? %>
+  <div class="fe-definition-list">
+    <% @definitions.each do |definition| %>
+      <div class="fe-definition-card">
+        <h2><%= definition.name %> <small>v<%= definition.version %></small></h2>
+        <%= link_to "Start",
+              flow_engine.sessions_path(definition_id: definition.id, **(@embed_mode ? { embed: "true" } : {})),
+              class: "fe-btn fe-btn--primary",
+              data: { turbo_method: :post } %>
+      </div>
+    <% end %>
+  </div>
+<% else %>
+  <p>No active flow definitions available.</p>
+<% end %>

data/app/views/flow_engine/sessions/show.html.erb

@@ -0,0 +1,26 @@
+<div class="fe-session" data-controller="step">
+  <div class="fe-progress" data-controller="progress" data-progress-value="<%= @progress %>">
+    <div class="fe-progress__bar" style="width: <%= @progress %>%"></div>
+  </div>
+  <span class="fe-progress__text">Step <%= @progress %>% complete</span>
+
+  <% if @node %>
+    <div class="fe-step">
+      <h2 class="fe-step__question"><%= @node.question %></h2>
+
+      <%= form_with url: flow_engine.session_path(@flow_session, **embed_mode? ? { embed: "true" } : {}),
+                    method: :patch,
+                    local: true,
+                    data: { step_target: "form" } do |form| %>
+
+        <%= render_step(@node, form) %>
+
+        <div class="fe-step__actions">
+          <%= form.submit "Continue", class: "fe-btn fe-btn--primary", data: { step_target: "submit" } %>
+        </div>
+      <% end %>
+    </div>
+  <% else %>
+    <p>This session has no current step.</p>
+  <% end %>
+</div>

data/app/views/flow_engine/sessions/steps/_boolean.html.erb

@@ -0,0 +1,10 @@
+<div class="fe-field fe-field--boolean">
+  <label class="fe-radio">
+    <input type="radio" name="answer" value="true">
+    <span>Yes</span>
+  </label>
+  <label class="fe-radio">
+    <input type="radio" name="answer" value="false">
+    <span>No</span>
+  </label>
+</div>

data/app/views/flow_engine/sessions/steps/_display.html.erb

@@ -0,0 +1,4 @@
+<div class="fe-field fe-field--display">
+  <p class="fe-display-text"><%= node.question %></p>
+  <input type="hidden" name="answer" value="acknowledged">
+</div>

data/app/views/flow_engine/sessions/steps/_multi_select.html.erb

@@ -0,0 +1,8 @@
+<div class="fe-field fe-field--multi-select">
+  <% (node.options || []).each do |option| %>
+    <label class="fe-checkbox">
+      <input type="checkbox" name="answer_values[]" value="<%= option %>">
+      <span><%= option %></span>
+    </label>
+  <% end %>
+</div>

data/app/views/flow_engine/sessions/steps/_number.html.erb

@@ -0,0 +1,3 @@
+<div class="fe-field fe-field--number">
+  <input type="number" name="answer" value="0" min="0" class="fe-input fe-input--number">
+</div>

data/app/views/flow_engine/sessions/steps/_number_matrix.html.erb

@@ -0,0 +1,13 @@
+<div class="fe-field fe-field--number-matrix">
+  <% (node.fields || []).each do |field_name| %>
+    <div class="fe-matrix-row">
+      <label class="fe-matrix-row__label" for="answer_fields_<%= field_name %>"><%= field_name %></label>
+      <input type="number"
+             name="answer_fields[<%= field_name %>]"
+             id="answer_fields_<%= field_name %>"
+             value="0"
+             min="0"
+             class="fe-input fe-input--number">
+    </div>
+  <% end %>
+</div>

data/app/views/flow_engine/sessions/steps/_single_select.html.erb

@@ -0,0 +1,8 @@
+<div class="fe-field fe-field--single-select">
+  <% (node.options || []).each do |option| %>
+    <label class="fe-radio">
+      <input type="radio" name="answer" value="<%= option %>">
+      <span><%= option %></span>
+    </label>
+  <% end %>
+</div>

data/app/views/flow_engine/sessions/steps/_text.html.erb

@@ -0,0 +1,11 @@
+<div class="fe-field fe-field--text">
+  <textarea name="answer"
+            rows="6"
+            class="fe-input fe-input--textarea"
+            placeholder="<%= node.decorations&.dig(:placeholder) || "Type your answer here..." %>"
+            <% if node.decorations&.dig(:maxlength) %>maxlength="<%= node.decorations[:maxlength] %>"<% end %>
+  ></textarea>
+  <% if node.decorations&.dig(:hint) %>
+    <p class="fe-field__hint"><%= node.decorations[:hint] %></p>
+  <% end %>
+</div>

data/app/views/flow_engine/sessions/steps/_unknown.html.erb

@@ -0,0 +1,4 @@
+<div class="fe-field fe-field--unknown">
+  <p class="fe-field__hint">Unknown step type: <%= node.type %></p>
+  <textarea name="answer" rows="4" class="fe-input fe-input--textarea" placeholder="Enter your answer..."></textarea>
+</div>

data/app/views/layouts/flow_engine/application.html.erb

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>FlowEngine</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=JetBrains+Mono:wght@400;500&display=swap">
+  <link rel="stylesheet" href="<%= flow_engine.root_path %>assets/flow_engine/application.css">
+</head>
+<body>
+  <div class="fe-container">
+    <% if flash[:notice] %>
+      <div class="fe-flash fe-flash--notice"><%= flash[:notice] %></div>
+    <% end %>
+    <% if flash[:alert] %>
+      <div class="fe-flash fe-flash--alert"><%= flash[:alert] %></div>
+    <% end %>
+
+    <%= yield %>
+  </div>
+</body>
+</html>

data/app/views/layouts/flow_engine/embed.html.erb

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <%= csrf_meta_tags %>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=JetBrains+Mono:wght@400;500&display=swap">
+  <link rel="stylesheet" href="<%= flow_engine.root_path %>assets/flow_engine/application.css">
+  <style>
+    body { margin: 0; padding: 0; background: transparent; }
+    .fe-container { --fe-max-width: 100%; padding: var(--fe-space-md); }
+  </style>
+</head>
+<body>
+  <div class="fe-container">
+    <%= yield %>
+  </div>
+
+  <script>
+    function postResize() {
+      var height = document.body.scrollHeight;
+      window.parent.postMessage({ type: 'flowengine:resize', height: height }, '*');
+    }
+    window.addEventListener('load', postResize);
+    new MutationObserver(postResize).observe(document.body, { childList: true, subtree: true });
+  </script>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+FlowEngine::Rails::Engine.routes.draw do
+  resources :sessions, only: %i[new create show update] do
+    member do
+      get :completed
+      patch :abandon
+    end
+  end
+
+  namespace :admin do
+    resources :definitions do
+      member do
+        post :activate
+        post :deactivate
+        get :mermaid
+      end
+    end
+  end
+
+  root to: "sessions#new"
+end