bpmn-js-rails 0.1.0

data/app/helpers/bpmn_js_rails/view_helper.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module BpmnJsRails
+  module ViewHelper
+    # ── form-js assets ───────────────────────────────────────────────
+
+    # Render <link> and <script> tags for form-js assets.
+    #
+    #   <%= form_js_assets %>                    # viewer only
+    #   <%= form_js_assets(:viewer, :editor) %>  # both viewer and editor
+    #
+    def form_js_assets(*components)
+      components = [ :viewer ] if components.empty?
+      tags = []
+
+      tags << tag.link(
+        rel: "stylesheet",
+        href: "https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:ital,wght@0,400;0,600;1,400&display=swap"
+      )
+
+      tags << stylesheet_link_tag("form-js/form-js", "data-turbo-track": "reload")
+
+      if components.include?(:editor)
+        tags << stylesheet_link_tag("form-js/form-js-editor", "data-turbo-track": "reload")
+      end
+
+      if components.include?(:viewer)
+        tags << javascript_include_tag("form-js/form-viewer.umd", "data-turbo-track": "reload")
+      end
+
+      if components.include?(:editor)
+        tags << javascript_include_tag("form-js/form-editor.umd", "data-turbo-track": "reload")
+      end
+
+      safe_join(tags, "\n")
+    end
+
+    # Render a form-js viewer that displays/fills a form.
+    #
+    #   <%= form_js_viewer(@form) %>
+    #   <%= form_js_viewer(@form, data: { name: "John" }) %>
+    #   <%= form_js_viewer({ type: "default", components: [...] }) %>
+    #
+    def form_js_viewer(form_or_schema, data: {}, **html_options)
+      schema = extract_schema(form_or_schema)
+
+      html_options[:class] = Array(html_options[:class]).push("form-js-viewer-container").join(" ")
+      html_options[:style] = [ html_options[:style], "min-height: 200px" ].compact.join("; ")
+
+      html_options[:data] = (html_options[:data] || {}).merge(
+        controller: "form-js-viewer",
+        form_js_viewer_schema_value: schema.to_json,
+        form_js_viewer_data_value: data.to_json
+      )
+
+      content_tag(:div, "", **html_options)
+    end
+
+    # Render a form-js editor for designing forms.
+    #
+    #   <%= form_js_editor(@form) %>
+    #   <%= form_js_editor(@form, field_name: "form[schema]") %>
+    #
+    def form_js_editor(form_or_schema, field_name: nil, **html_options)
+      schema = extract_schema(form_or_schema)
+
+      html_options[:class] = Array(html_options[:class]).push("form-js-editor-container").join(" ")
+
+      html_options[:data] = (html_options[:data] || {}).merge(
+        controller: "form-js-editor",
+        form_js_editor_schema_value: schema.to_json
+      )
+
+      content_tag(:div, **html_options) do
+        children = []
+        children << content_tag(:div, "", style: "min-height: 500px", data: { form_js_editor_target: "container" })
+
+        if field_name
+          children << tag.input(
+            type: "hidden",
+            name: field_name,
+            value: schema.to_json,
+            data: { form_js_editor_target: "schemaField" }
+          )
+        end
+
+        safe_join(children)
+      end
+    end
+
+    # ── bpmn-js assets ───────────────────────────────────────────────
+
+    # Render <link> and <script> tags for bpmn-js assets.
+    #
+    #   <%= bpmn_js_assets %>                      # viewer only
+    #   <%= bpmn_js_assets(:viewer, :modeler) %>   # both viewer and modeler
+    #
+    def bpmn_js_assets(*components)
+      components = [ :viewer ] if components.empty?
+      tags = []
+
+      tags << stylesheet_link_tag("bpmn-js/diagram-js", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("bpmn-js/bpmn-js", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("bpmn-js/bpmn-font/css/bpmn-embedded", "data-turbo-track": "reload")
+
+      if components.include?(:viewer) && !components.include?(:modeler)
+        tags << javascript_include_tag("bpmn-js/bpmn-viewer.production.min", "data-turbo-track": "reload")
+      end
+
+      if components.include?(:modeler)
+        tags << javascript_include_tag("bpmn-js/bpmn-modeler.production.min", "data-turbo-track": "reload")
+      end
+
+      safe_join(tags, "\n")
+    end
+
+    # Render a bpmn-js viewer that displays a BPMN diagram (read-only).
+    #
+    #   <%= bpmn_js_viewer(@diagram) %>
+    #   <%= bpmn_js_viewer("<bpmn:definitions ...>...</bpmn:definitions>") %>
+    #
+    def bpmn_js_viewer(diagram_or_xml, **html_options)
+      xml = extract_xml(diagram_or_xml)
+
+      html_options[:class] = Array(html_options[:class]).push("bpmn-js-viewer-container").join(" ")
+      html_options[:style] = [ html_options[:style], "height: 500px" ].compact.join("; ")
+
+      html_options[:data] = (html_options[:data] || {}).merge(
+        controller: "bpmn-js-viewer",
+        bpmn_js_viewer_xml_value: xml
+      )
+
+      content_tag(:div, "", **html_options)
+    end
+
+    # Render a bpmn-js modeler for designing BPMN diagrams.
+    #
+    #   <%= bpmn_js_modeler(@diagram) %>
+    #   <%= bpmn_js_modeler(@diagram, field_name: "diagram[xml]") %>
+    #
+    def bpmn_js_modeler(diagram_or_xml, field_name: nil, **html_options)
+      xml = extract_xml(diagram_or_xml)
+
+      html_options[:class] = Array(html_options[:class]).push("bpmn-js-modeler-container").join(" ")
+
+      html_options[:data] = (html_options[:data] || {}).merge(
+        controller: "bpmn-js-modeler",
+        bpmn_js_modeler_xml_value: xml
+      )
+
+      content_tag(:div, **html_options) do
+        children = []
+        children << content_tag(:div, "", style: "height: 500px", data: { bpmn_js_modeler_target: "container" })
+
+        if field_name
+          children << tag.input(
+            type: "hidden",
+            name: field_name,
+            value: xml,
+            data: { bpmn_js_modeler_target: "xmlField" }
+          )
+        end
+
+        safe_join(children)
+      end
+    end
+
+    # ── dmn-js assets ────────────────────────────────────────────────
+
+    # Render <link> and <script> tags for dmn-js assets.
+    #
+    #   <%= dmn_js_assets %>                       # viewer only
+    #   <%= dmn_js_assets(:viewer, :modeler) %>    # both viewer and modeler
+    #
+    def dmn_js_assets(*components)
+      components = [ :viewer ] if components.empty?
+      tags = []
+
+      tags << stylesheet_link_tag("dmn-js/diagram-js", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("dmn-js/dmn-js-shared", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("dmn-js/dmn-js-drd", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("dmn-js/dmn-js-decision-table", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("dmn-js/dmn-js-literal-expression", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("dmn-js/dmn-js-boxed-expression", "data-turbo-track": "reload")
+      tags << stylesheet_link_tag("dmn-js/dmn-font/css/dmn-embedded", "data-turbo-track": "reload")
+
+      if components.include?(:modeler)
+        tags << stylesheet_link_tag("dmn-js/dmn-js-decision-table-controls", "data-turbo-track": "reload")
+        tags << stylesheet_link_tag("dmn-js/dmn-js-boxed-expression-controls", "data-turbo-track": "reload")
+      end
+
+      if components.include?(:viewer) && !components.include?(:modeler)
+        tags << javascript_include_tag("dmn-js/dmn-viewer.production.min", "data-turbo-track": "reload")
+      end
+
+      if components.include?(:modeler)
+        tags << javascript_include_tag("dmn-js/dmn-modeler.production.min", "data-turbo-track": "reload")
+      end
+
+      safe_join(tags, "\n")
+    end
+
+    # Render a dmn-js viewer that displays a DMN decision (read-only).
+    #
+    #   <%= dmn_js_viewer(@decision) %>
+    #   <%= dmn_js_viewer("<definitions ...>...</definitions>") %>
+    #
+    def dmn_js_viewer(decision_or_xml, **html_options)
+      xml = extract_dmn_xml(decision_or_xml)
+
+      html_options[:class] = Array(html_options[:class]).push("dmn-js-viewer-container").join(" ")
+      html_options[:style] = [ html_options[:style], "height: 500px" ].compact.join("; ")
+
+      html_options[:data] = (html_options[:data] || {}).merge(
+        controller: "dmn-js-viewer",
+        dmn_js_viewer_xml_value: xml
+      )
+
+      content_tag(:div, "", **html_options)
+    end
+
+    # Render a dmn-js modeler for designing DMN decisions.
+    #
+    #   <%= dmn_js_modeler(@decision) %>
+    #   <%= dmn_js_modeler(@decision, field_name: "decision[xml]") %>
+    #
+    def dmn_js_modeler(decision_or_xml, field_name: nil, **html_options)
+      xml = extract_dmn_xml(decision_or_xml)
+
+      html_options[:class] = Array(html_options[:class]).push("dmn-js-modeler-container").join(" ")
+
+      html_options[:data] = (html_options[:data] || {}).merge(
+        controller: "dmn-js-modeler",
+        dmn_js_modeler_xml_value: xml
+      )
+
+      content_tag(:div, **html_options) do
+        children = []
+        children << content_tag(:div, "", style: "height: 500px", data: { dmn_js_modeler_target: "container" })
+
+        if field_name
+          children << tag.input(
+            type: "hidden",
+            name: field_name,
+            value: xml,
+            data: { dmn_js_modeler_target: "xmlField" }
+          )
+        end
+
+        safe_join(children)
+      end
+    end
+
+    private
+
+    def extract_schema(form_or_schema)
+      case form_or_schema
+      when BpmnJsRails::Form
+        form_or_schema.schema || { "type" => "default", "components" => [] }
+      when Hash
+        form_or_schema
+      when String
+        JSON.parse(form_or_schema)
+      else
+        form_or_schema.try(:schema) || { "type" => "default", "components" => [] }
+      end
+    end
+
+    def extract_xml(diagram_or_xml)
+      case diagram_or_xml
+      when BpmnJsRails::Diagram
+        diagram_or_xml.xml || BpmnJsRails::Diagram::DEFAULT_XML
+      when String
+        diagram_or_xml
+      else
+        diagram_or_xml.try(:xml) || BpmnJsRails::Diagram::DEFAULT_XML
+      end
+    end
+
+    def extract_dmn_xml(decision_or_xml)
+      case decision_or_xml
+      when BpmnJsRails::Decision
+        decision_or_xml.xml || BpmnJsRails::Decision::DEFAULT_XML
+      when String
+        decision_or_xml
+      else
+        decision_or_xml.try(:xml) || BpmnJsRails::Decision::DEFAULT_XML
+      end
+    end
+  end
+end

data/app/javascript/bpmn_js_rails/controllers/bpmn_js_modeler_controller.js

@@ -0,0 +1,85 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="bpmn-js-modeler"
+//
+// Values:
+//   xml (String) - the BPMN 2.0 XML to load into the modeler
+//
+// Targets:
+//   container - the child div that bpmn-js renders into (falls back to this.element)
+//   xmlField  - a hidden <input> that receives the serialised XML
+//               on every change and before form submission
+//
+// Lifecycle:
+//   connect:    creates the BpmnJS modeler instance, imports XML, wires change + submit sync
+//   disconnect: destroys the modeler
+//
+// Events dispatched on the controller element:
+//   bpmn-js-modeler:ready   - { detail: { modeler } }
+//   bpmn-js-modeler:changed - after XML sync
+//
+export default class extends Controller {
+  static values = {
+    xml: { type: String, default: "" }
+  }
+
+  static targets = ["container", "xmlField"]
+
+  async connect() {
+    if (typeof BpmnJS === "undefined") {
+      console.error("[bpmn-js-rails] BpmnJS global not found. Make sure bpmn-modeler.production.min.js is loaded.")
+      return
+    }
+
+    const renderTarget = this.hasContainerTarget ? this.containerTarget : this.element
+
+    this.modeler = new BpmnJS({ container: renderTarget })
+
+    if (this.xmlValue) {
+      try {
+        await this.modeler.importXML(this.xmlValue)
+        this.modeler.get("canvas").zoom("fit-viewport")
+      } catch (err) {
+        console.error("[bpmn-js-rails] Failed to import XML:", err)
+      }
+    }
+
+    this.modeler.on("commandStack.changed", () => {
+      this._syncXmlField()
+      this.dispatch("changed")
+    })
+
+    // Also sync right before the enclosing <form> submits
+    this._form = this.element.closest("form")
+    if (this._form) {
+      this._boundSubmitHandler = () => this._syncXmlField()
+      this._form.addEventListener("submit", this._boundSubmitHandler)
+    }
+
+    this.dispatch("ready", { detail: { modeler: this.modeler } })
+  }
+
+  disconnect() {
+    if (this._form && this._boundSubmitHandler) {
+      this._form.removeEventListener("submit", this._boundSubmitHandler)
+      this._boundSubmitHandler = null
+      this._form = null
+    }
+
+    if (this.modeler) {
+      this.modeler.destroy()
+      this.modeler = null
+    }
+  }
+
+  // Serialise the current modeler XML into the hidden field target.
+  async _syncXmlField() {
+    if (!this.modeler || !this.hasXmlFieldTarget) return
+    try {
+      const { xml } = await this.modeler.saveXML({ format: true })
+      this.xmlFieldTarget.value = xml
+    } catch (_) {
+      // modeler may be mid-import; ignore
+    }
+  }
+}

data/app/javascript/bpmn_js_rails/controllers/bpmn_js_viewer_controller.js

@@ -0,0 +1,46 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="bpmn-js-viewer"
+//
+// Values:
+//   xml (String) - the BPMN 2.0 XML to display
+//
+// Lifecycle:
+//   connect:    creates the BpmnJS viewer instance, imports XML
+//   disconnect: destroys it (cleans up DOM + listeners)
+//
+// Events dispatched on the controller element:
+//   bpmn-js-viewer:loaded - { detail: { warnings } }
+//   bpmn-js-viewer:error  - { detail: { error } }
+//
+export default class extends Controller {
+  static values = {
+    xml: { type: String, default: "" }
+  }
+
+  async connect() {
+    if (typeof BpmnJS === "undefined") {
+      console.error("[bpmn-js-rails] BpmnJS global not found. Make sure bpmn-viewer.production.min.js or bpmn-modeler.production.min.js is loaded.")
+      return
+    }
+
+    this.viewer = new BpmnJS({ container: this.element })
+
+    if (this.xmlValue) {
+      try {
+        const result = await this.viewer.importXML(this.xmlValue)
+        this.viewer.get("canvas").zoom("fit-viewport")
+        this.dispatch("loaded", { detail: { warnings: result.warnings } })
+      } catch (err) {
+        this.dispatch("error", { detail: { error: err } })
+      }
+    }
+  }
+
+  disconnect() {
+    if (this.viewer) {
+      this.viewer.destroy()
+      this.viewer = null
+    }
+  }
+}

data/app/javascript/bpmn_js_rails/controllers/dmn_js_modeler_controller.js

@@ -0,0 +1,102 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="dmn-js-modeler"
+//
+// Values:
+//   xml (String) - the DMN 1.3 XML to load into the modeler
+//
+// Targets:
+//   container - the child div that dmn-js renders into (falls back to this.element)
+//   xmlField  - a hidden <input> that receives the serialised XML
+//               on every change and before form submission
+//
+// Lifecycle:
+//   connect:    creates the DmnJS modeler instance, imports XML, wires change + submit sync
+//   disconnect: destroys the modeler
+//
+// Events dispatched on the controller element:
+//   dmn-js-modeler:ready   - { detail: { modeler } }
+//   dmn-js-modeler:changed - after XML sync
+//
+export default class extends Controller {
+  static values = {
+    xml: { type: String, default: "" }
+  }
+
+  static targets = ["container", "xmlField"]
+
+  async connect() {
+    if (typeof DmnJS === "undefined") {
+      console.error("[bpmn-js-rails] DmnJS global not found. Make sure dmn-modeler.production.min.js is loaded.")
+      return
+    }
+
+    const renderTarget = this.hasContainerTarget ? this.containerTarget : this.element
+
+    this.modeler = new DmnJS({
+      container: renderTarget,
+      keyboard: { bindTo: window }
+    })
+
+    if (this.xmlValue) {
+      try {
+        await this.modeler.importXML(this.xmlValue)
+      } catch (err) {
+        console.error("[bpmn-js-rails] Failed to import DMN XML:", err)
+      }
+    }
+
+    // Listen for changes on the active viewer's command stack
+    this.modeler.on("views.changed", ({ activeView }) => {
+      const activeViewer = this.modeler.getActiveViewer()
+      if (activeViewer && this._currentViewer !== activeViewer) {
+        this._currentViewer = activeViewer
+
+        try {
+          const eventBus = activeViewer.get("eventBus")
+          eventBus.on("commandStack.changed", () => {
+            this._syncXmlField()
+            this.dispatch("changed")
+          })
+        } catch (_) {
+          // some view types may not have a commandStack
+        }
+      }
+    })
+
+    // Also sync right before the enclosing <form> submits
+    this._form = this.element.closest("form")
+    if (this._form) {
+      this._boundSubmitHandler = () => this._syncXmlField()
+      this._form.addEventListener("submit", this._boundSubmitHandler)
+    }
+
+    this.dispatch("ready", { detail: { modeler: this.modeler } })
+  }
+
+  disconnect() {
+    if (this._form && this._boundSubmitHandler) {
+      this._form.removeEventListener("submit", this._boundSubmitHandler)
+      this._boundSubmitHandler = null
+      this._form = null
+    }
+
+    this._currentViewer = null
+
+    if (this.modeler) {
+      this.modeler.destroy()
+      this.modeler = null
+    }
+  }
+
+  // Serialise the current modeler XML into the hidden field target.
+  async _syncXmlField() {
+    if (!this.modeler || !this.hasXmlFieldTarget) return
+    try {
+      const { xml } = await this.modeler.saveXML({ format: true })
+      this.xmlFieldTarget.value = xml
+    } catch (_) {
+      // modeler may be mid-import; ignore
+    }
+  }
+}

data/app/javascript/bpmn_js_rails/controllers/dmn_js_viewer_controller.js

@@ -0,0 +1,45 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="dmn-js-viewer"
+//
+// Values:
+//   xml (String) - the DMN 1.3 XML to display
+//
+// Lifecycle:
+//   connect:    creates the DmnJS viewer instance, imports XML
+//   disconnect: destroys it (cleans up DOM + listeners)
+//
+// Events dispatched on the controller element:
+//   dmn-js-viewer:loaded - { detail: { warnings } }
+//   dmn-js-viewer:error  - { detail: { error } }
+//
+export default class extends Controller {
+  static values = {
+    xml: { type: String, default: "" }
+  }
+
+  async connect() {
+    if (typeof DmnJS === "undefined") {
+      console.error("[bpmn-js-rails] DmnJS global not found. Make sure dmn-viewer.production.min.js or dmn-modeler.production.min.js is loaded.")
+      return
+    }
+
+    this.viewer = new DmnJS({ container: this.element })
+
+    if (this.xmlValue) {
+      try {
+        const result = await this.viewer.importXML(this.xmlValue)
+        this.dispatch("loaded", { detail: { warnings: result.warnings } })
+      } catch (err) {
+        this.dispatch("error", { detail: { error: err } })
+      }
+    }
+  }
+
+  disconnect() {
+    if (this.viewer) {
+      this.viewer.destroy()
+      this.viewer = null
+    }
+  }
+}

data/app/javascript/bpmn_js_rails/controllers/form_js_editor_controller.js

@@ -0,0 +1,80 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="form-js-editor"
+//
+// Values:
+//   schema (Object) - the form-js JSON schema to load into the editor
+//
+// Targets:
+//   container   - the child div that form-js renders into (falls back to this.element)
+//   schemaField - a hidden <input> that receives the serialised schema JSON
+//                 on every change and before form submission
+//
+// Lifecycle:
+//   connect:    creates the FormEditor instance, wires change + submit sync
+//   disconnect: destroys the editor
+//
+// Events dispatched on the controller element:
+//   form-js:editor:ready   - { detail: { editor } }
+//   form-js:editor:changed - after schema sync
+//
+export default class extends Controller {
+  static values = {
+    schema: { type: Object, default: { type: "default", components: [] } }
+  }
+
+  static targets = ["container", "schemaField"]
+
+  connect() {
+    if (typeof FormEditor === "undefined") {
+      console.error("[bpmn-js-rails] FormEditor global not found. Make sure form-editor.umd.js is loaded.")
+      return
+    }
+
+    const renderTarget = this.hasContainerTarget ? this.containerTarget : this.element
+
+    FormEditor.createFormEditor({
+      container: renderTarget,
+      schema: this.schemaValue
+    }).then((editor) => {
+      this.editor = editor
+
+      editor.on("changed", () => {
+        this._syncSchemaField()
+        this.dispatch("changed")
+      })
+
+      // Also sync right before the enclosing <form> submits
+      this._form = this.element.closest("form")
+      if (this._form) {
+        this._boundSubmitHandler = () => this._syncSchemaField()
+        this._form.addEventListener("submit", this._boundSubmitHandler)
+      }
+
+      this.dispatch("ready", { detail: { editor } })
+    })
+  }
+
+  disconnect() {
+    if (this._form && this._boundSubmitHandler) {
+      this._form.removeEventListener("submit", this._boundSubmitHandler)
+      this._boundSubmitHandler = null
+      this._form = null
+    }
+
+    if (this.editor) {
+      this.editor.destroy()
+      this.editor = null
+    }
+  }
+
+  // Serialise the current editor schema into the hidden field target.
+  _syncSchemaField() {
+    if (!this.editor || !this.hasSchemaFieldTarget) return
+    try {
+      this.schemaFieldTarget.value = JSON.stringify(this.editor.saveSchema())
+    } catch (_) {
+      // editor may be mid-import; ignore
+    }
+  }
+}